opencti-mcp 0.1.0__tar.gz

opencti_mcp-0.1.0/.env.example

@@ -0,0 +1,11 @@
+# Required
+OPENCTI_URL=https://your-opencti-instance.example.com/
+OPENCTI_TOKEN=your-api-token-here
+
+# Optional
+OPENCTI_READ_ONLY=true
+OPENCTI_TIMEOUT=30
+OPENCTI_SSL_VERIFY=true
+LOG_LEVEL=INFO
+MCP_HTTP_HOST=127.0.0.1
+MCP_HTTP_PORT=8765

opencti_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv venv --python ${{ matrix.python-version }}
+      - run: uv pip install -e ".[dev]"
+      - run: uv run ruff check .
+      - run: uv run pytest -q

opencti_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when a GitHub Release is published, using PyPI Trusted
+# Publishing (OIDC) — no API token or secret is stored anywhere.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # REQUIRED for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

opencti_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Local Claude Code / editor state
+.claude/
+
+# Internal development docs (brainstorm specs + implementation plans) — kept local, not published
+docs/superpowers/

opencti_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0]
+
+- Initial release

opencti_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

opencti_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kierston Grantham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opencti_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: opencti-mcp
+Version: 0.1.0
+Summary: MCP server exposing the OpenCTI threat-intelligence platform to AI assistants.
+Project-URL: Homepage, https://github.com/Space-C0wboy/OpenCTI-MCP-Server
+Project-URL: Repository, https://github.com/Space-C0wboy/OpenCTI-MCP-Server
+Project-URL: Issues, https://github.com/Space-C0wboy/OpenCTI-MCP-Server/issues
+Author: Kierston Grantham
+License: MIT
+License-File: LICENSE
+Keywords: cti,fastmcp,mcp,model-context-protocol,opencti,pycti,security,stix,threat-intelligence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<3.0,>=2.0.0
+Requires-Dist: pycti>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenCTI MCP Server
+
+[![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io)
+[![CI](https://github.com/Space-C0wboy/OpenCTI-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/Space-C0wboy/OpenCTI-MCP-Server/actions/workflows/ci.yml)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **OpenCTI**, the open-source threat-intelligence platform, to AI assistants. Built on the official `pycti` client, it registers 45 typed tools (91 when writes are enabled) across 15 threat-intel domains — indicators, observables, reports, malware, threat actors, intrusion sets, campaigns, attack patterns, tools, vulnerabilities, incidents, cases, relationships, identities, and labels/markings — plus platform/operations tools (connectors, users, groups, files), STIX bundle import/export, a `graphql_query` escape-hatch, and cross-cutting search/relationship/observable-lookup tools for anything the typed per-domain tools don't cover.
+
+> [!IMPORTANT]
+> This is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or supported by Filigran or the OpenCTI project.
+
+> [!WARNING]
+> **Ships read-only by default.** With the default configuration, only list/get/query tools are registered and `graphql_query` rejects mutations. Setting `OPENCTI_READ_ONLY=false` exposes `*_create`, `*_update`, and the destructive `*_delete` tools, and lets `graphql_query` run mutations. Only enable writes with a least-privilege OpenCTI API token, and understand that an assistant with write access can create, modify, and permanently delete intelligence data in your instance.
+
+## Tools
+
+| Domain | Reads | Writes | Notable tools |
+| --- | :---: | :---: | --- |
+| Indicators | 2 | 3 | `indicators_list`, `indicators_get`, `indicators_create` |
+| Observables | 2 | 3 | `observables_list`, `observables_get`, `observables_create` |
+| Reports | 2 | 3 | `reports_list`, `reports_get`, `reports_create` |
+| Malware | 2 | 3 | `malware_list`, `malware_get`, `malware_create` |
+| Threat actors | 2 | 3 | `threat_actors_list`, `threat_actors_get`, `threat_actors_create` |
+| Intrusion sets | 2 | 3 | `intrusion_sets_list`, `intrusion_sets_get`, `intrusion_sets_create` |
+| Campaigns | 2 | 3 | `campaigns_list`, `campaigns_get`, `campaigns_create` |
+| Attack patterns | 2 | 3 | `attack_patterns_list`, `attack_patterns_get`, `attack_patterns_create` |
+| Tools | 2 | 3 | `tools_list`, `tools_get`, `tools_create` |
+| Vulnerabilities | 2 | 3 | `vulnerabilities_list`, `vulnerabilities_get`, `vulnerabilities_create` |
+| Incidents | 2 | 3 | `incidents_list`, `incidents_get`, `incidents_create` |
+| Cases | 2 | 3 | `cases_list`, `cases_get`, `cases_create` |
+| Relationships | 2 | 3 | `relationships_list`, `relationships_get`, `relationships_create` |
+| Identities | 2 | 2 | `identities_list`, `identities_get`, `identities_create` (organizations/individuals/systems/sectors), `identities_delete` |
+| Labels & markings | 4 | 3 | `labels_list`, `labels_create`, `markings_list`, `markings_get` |
+
+Every domain also has an `_update` and `_delete` tool once writes are enabled (markings are read-only; identities has `_create`/`_delete` but no `_update`). In addition, `graphql_query` runs a raw GraphQL query/mutation against the OpenCTI API for anything not covered by a typed tool above — reads always work, mutations are rejected unless `OPENCTI_READ_ONLY=false`. See [`docs/ENDPOINTS.md`](docs/ENDPOINTS.md) for the full tool-to-`pycti`-call mapping.
+
+Every `*_list` tool also accepts `order_by` (a field name, e.g. `"created_at"`) and `descending` (default `true`), so `order_by="created_at"` gives most-recent-first without any extra filtering.
+
+`observables_create` also accepts `StixFile.*` observable keys (normalized to `File.*`), coerces `Autonomous-System.number` values to an integer, and takes an optional `additional_hashes` param (a list of `"ALGO:VALUE"` entries, e.g. `"SHA-1:..."`) to attach extra hashes to a file observable alongside the primary one.
+
+### Cross-cutting read tools
+
+- `search_all(query, types?, first?)` — full-text search across all STIX object types at once, optionally restricted to specific `types`.
+- `relationships_for_entity(entity_id, relationship_type?, first?)` — lists relationships touching an entity as either source or target, e.g. "what is related to X".
+- `observables_by_value(value, first?)` — exact-value lookup for an observable (IP, domain, URL, hash, etc.) without knowing its id.
+
+### Platform & operations
+
+- `connectors_list` / `connectors_get(connector_id)` — list connectors and check one's status/health (active, state, queue details).
+- `users_list` / `users_get(id)` — list/get OpenCTI users.
+- `groups_list` / `groups_get(id)` — list/get OpenCTI groups.
+- `files_for_entity(entity_id)` — list files/attachments on an entity.
+- `stix_export_entity(entity_type, entity_id, mode?)` / `stix_export_list(entity_type, first=25, mode?)` — export a single entity, or up to `first` entities of a type (max 500), as a STIX 2 bundle; large exports are capped by `first`, and if the bundle is still too large a small note (`_note`, `entity_type`, `first`, `object_count`) is returned instead.
+- `stix_import_bundle(bundle_json, update?)` — **write, requires `OPENCTI_READ_ONLY=false`** — bulk create/update entities and relationships from a STIX bundle.
+- `entity_ask_enrichment(entity_id, connector_id)` — **write, requires `OPENCTI_READ_ONLY=false`** — trigger a connector to enrich an entity.
+
+Two related capabilities are intentionally not exposed as typed tools and remain available via `graphql_query`: OpenCTI status templates, and connector start/stop/reset (`pycti` exposes no dedicated method for either).
+
+## Bundled skill
+
+A **Claude Skill** lives at [`skills/opencti-usage/`](skills/opencti-usage/) that teaches an AI agent OpenCTI's model — the STIX data model, entity types, indicators vs observables, relationships, containers, TLP markings, confidence, connectors, and RBAC — and maps each concept to the right MCP tool above. An agent operating the `opencti` tools loads this skill to understand the platform before creating, relating, or reasoning about OpenCTI data.
+
+- [`skills/opencti-usage/SKILL.md`](skills/opencti-usage/SKILL.md) is the entry point; the `references/` folder holds the per-topic detail.
+- The content is distilled from the official OpenCTI docs (`docs.opencti.io/latest`), distilled 2026-07-10. Each reference file has a `## Source` link back to the docs it was drawn from, so it can be refreshed later.
+
+## Quick start
+
+### Install
+
+```bash
+git clone https://github.com/Space-C0wboy/OpenCTI-MCP-Server.git
+cd OpenCTI-MCP-Server
+uv venv
+uv pip install -e ".[dev]"
+```
+
+Or with plain `pip`:
+
+```bash
+pip install -e .
+```
+
+### Get an API token
+
+In OpenCTI, open your profile menu → **API access**, then copy your personal access token.
+
+### Configuration
+
+Configuration is read from environment variables, or from a `.env` file in the working directory (either a standard `KEY=value` dotenv file or a JSON-style fragment). OS environment variables always take precedence over the file.
+
+| Variable | Required | Default | Description |
+| --- | :---: | --- | --- |
+| `OPENCTI_URL` | Yes | — | Base URL of your OpenCTI instance |
+| `OPENCTI_TOKEN` | Yes | — | OpenCTI API token |
+| `OPENCTI_READ_ONLY` | No | `true` | When `true`, hides all write tools and blocks mutations |
+| `OPENCTI_TIMEOUT` | No | `30` | Request timeout in seconds |
+| `OPENCTI_SSL_VERIFY` | No | `true` | Verify TLS certificates |
+| `LOG_LEVEL` | No | `INFO` | Logging verbosity |
+| `MCP_HTTP_HOST` | No | `127.0.0.1` | Bind host when using `--transport http` |
+| `MCP_HTTP_PORT` | No | `8765` | Bind port when using `--transport http` |
+
+### Run
+
+Stdio (default, for editor/IDE integrations):
+
+```bash
+uv run opencti-mcp
+```
+
+HTTP transport:
+
+```bash
+uv run opencti-mcp --transport http --host 127.0.0.1 --port 8765
+```
+
+## Read-only mode
+
+`OPENCTI_READ_ONLY` defaults to `true`. In read-only mode, only list/get tools and `markings_list`/`markings_get` are registered — no `*_create`, `*_update`, or `*_delete` tool is available for any domain, and `graphql_query` raises an error if the query document contains a `mutation`. Set `OPENCTI_READ_ONLY=false` to register the write tools and allow `graphql_query` to run mutations.
+
+## Editor integration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "opencti": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/OpenCTI-MCP-Server", "run", "opencti-mcp"],
+      "env": {
+        "OPENCTI_URL": "https://your-opencti-instance.example.com/",
+        "OPENCTI_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add opencti -- uv --directory /absolute/path/to/OpenCTI-MCP-Server run opencti-mcp
+```
+
+## Example prompts
+
+- "List the 10 most recent indicators."
+- "Search reports mentioning 'Emotet'."
+- "Show me the MITRE ATT&CK technique T1059."
+- "Create an IPv4 observable for 1.2.3.4." (requires `OPENCTI_READ_ONLY=false`)
+- "Which threat actors are linked to intrusion set APT29?"
+- "Get the full detail on case CASE-ID, including its labels and markings."
+- "What are the 10 most recent reports?"
+- "Is 1.2.3.4 in OpenCTI?"
+- "What is this threat actor related to?"
+- "Search across everything for 'Emotet'."
+- "Are our OpenCTI connectors healthy?"
+- "Export this report as a STIX bundle."
+- "List the groups in OpenCTI."
+- "Add the victim organization 'Acme Corp' to OpenCTI." (requires `OPENCTI_READ_ONLY=false`)
+- "Create an individual identity for John Doe with a description."
+
+## Development
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Support
+
+This is a community-maintained project provided as-is, with no guaranteed support SLA. Issues and pull requests are welcome.

opencti_mcp-0.1.0/README.md

@@ -0,0 +1,179 @@
+# OpenCTI MCP Server
+
+[![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io)
+[![CI](https://github.com/Space-C0wboy/OpenCTI-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/Space-C0wboy/OpenCTI-MCP-Server/actions/workflows/ci.yml)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **OpenCTI**, the open-source threat-intelligence platform, to AI assistants. Built on the official `pycti` client, it registers 45 typed tools (91 when writes are enabled) across 15 threat-intel domains — indicators, observables, reports, malware, threat actors, intrusion sets, campaigns, attack patterns, tools, vulnerabilities, incidents, cases, relationships, identities, and labels/markings — plus platform/operations tools (connectors, users, groups, files), STIX bundle import/export, a `graphql_query` escape-hatch, and cross-cutting search/relationship/observable-lookup tools for anything the typed per-domain tools don't cover.
+
+> [!IMPORTANT]
+> This is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or supported by Filigran or the OpenCTI project.
+
+> [!WARNING]
+> **Ships read-only by default.** With the default configuration, only list/get/query tools are registered and `graphql_query` rejects mutations. Setting `OPENCTI_READ_ONLY=false` exposes `*_create`, `*_update`, and the destructive `*_delete` tools, and lets `graphql_query` run mutations. Only enable writes with a least-privilege OpenCTI API token, and understand that an assistant with write access can create, modify, and permanently delete intelligence data in your instance.
+
+## Tools
+
+| Domain | Reads | Writes | Notable tools |
+| --- | :---: | :---: | --- |
+| Indicators | 2 | 3 | `indicators_list`, `indicators_get`, `indicators_create` |
+| Observables | 2 | 3 | `observables_list`, `observables_get`, `observables_create` |
+| Reports | 2 | 3 | `reports_list`, `reports_get`, `reports_create` |
+| Malware | 2 | 3 | `malware_list`, `malware_get`, `malware_create` |
+| Threat actors | 2 | 3 | `threat_actors_list`, `threat_actors_get`, `threat_actors_create` |
+| Intrusion sets | 2 | 3 | `intrusion_sets_list`, `intrusion_sets_get`, `intrusion_sets_create` |
+| Campaigns | 2 | 3 | `campaigns_list`, `campaigns_get`, `campaigns_create` |
+| Attack patterns | 2 | 3 | `attack_patterns_list`, `attack_patterns_get`, `attack_patterns_create` |
+| Tools | 2 | 3 | `tools_list`, `tools_get`, `tools_create` |
+| Vulnerabilities | 2 | 3 | `vulnerabilities_list`, `vulnerabilities_get`, `vulnerabilities_create` |
+| Incidents | 2 | 3 | `incidents_list`, `incidents_get`, `incidents_create` |
+| Cases | 2 | 3 | `cases_list`, `cases_get`, `cases_create` |
+| Relationships | 2 | 3 | `relationships_list`, `relationships_get`, `relationships_create` |
+| Identities | 2 | 2 | `identities_list`, `identities_get`, `identities_create` (organizations/individuals/systems/sectors), `identities_delete` |
+| Labels & markings | 4 | 3 | `labels_list`, `labels_create`, `markings_list`, `markings_get` |
+
+Every domain also has an `_update` and `_delete` tool once writes are enabled (markings are read-only; identities has `_create`/`_delete` but no `_update`). In addition, `graphql_query` runs a raw GraphQL query/mutation against the OpenCTI API for anything not covered by a typed tool above — reads always work, mutations are rejected unless `OPENCTI_READ_ONLY=false`. See [`docs/ENDPOINTS.md`](docs/ENDPOINTS.md) for the full tool-to-`pycti`-call mapping.
+
+Every `*_list` tool also accepts `order_by` (a field name, e.g. `"created_at"`) and `descending` (default `true`), so `order_by="created_at"` gives most-recent-first without any extra filtering.
+
+`observables_create` also accepts `StixFile.*` observable keys (normalized to `File.*`), coerces `Autonomous-System.number` values to an integer, and takes an optional `additional_hashes` param (a list of `"ALGO:VALUE"` entries, e.g. `"SHA-1:..."`) to attach extra hashes to a file observable alongside the primary one.
+
+### Cross-cutting read tools
+
+- `search_all(query, types?, first?)` — full-text search across all STIX object types at once, optionally restricted to specific `types`.
+- `relationships_for_entity(entity_id, relationship_type?, first?)` — lists relationships touching an entity as either source or target, e.g. "what is related to X".
+- `observables_by_value(value, first?)` — exact-value lookup for an observable (IP, domain, URL, hash, etc.) without knowing its id.
+
+### Platform & operations
+
+- `connectors_list` / `connectors_get(connector_id)` — list connectors and check one's status/health (active, state, queue details).
+- `users_list` / `users_get(id)` — list/get OpenCTI users.
+- `groups_list` / `groups_get(id)` — list/get OpenCTI groups.
+- `files_for_entity(entity_id)` — list files/attachments on an entity.
+- `stix_export_entity(entity_type, entity_id, mode?)` / `stix_export_list(entity_type, first=25, mode?)` — export a single entity, or up to `first` entities of a type (max 500), as a STIX 2 bundle; large exports are capped by `first`, and if the bundle is still too large a small note (`_note`, `entity_type`, `first`, `object_count`) is returned instead.
+- `stix_import_bundle(bundle_json, update?)` — **write, requires `OPENCTI_READ_ONLY=false`** — bulk create/update entities and relationships from a STIX bundle.
+- `entity_ask_enrichment(entity_id, connector_id)` — **write, requires `OPENCTI_READ_ONLY=false`** — trigger a connector to enrich an entity.
+
+Two related capabilities are intentionally not exposed as typed tools and remain available via `graphql_query`: OpenCTI status templates, and connector start/stop/reset (`pycti` exposes no dedicated method for either).
+
+## Bundled skill
+
+A **Claude Skill** lives at [`skills/opencti-usage/`](skills/opencti-usage/) that teaches an AI agent OpenCTI's model — the STIX data model, entity types, indicators vs observables, relationships, containers, TLP markings, confidence, connectors, and RBAC — and maps each concept to the right MCP tool above. An agent operating the `opencti` tools loads this skill to understand the platform before creating, relating, or reasoning about OpenCTI data.
+
+- [`skills/opencti-usage/SKILL.md`](skills/opencti-usage/SKILL.md) is the entry point; the `references/` folder holds the per-topic detail.
+- The content is distilled from the official OpenCTI docs (`docs.opencti.io/latest`), distilled 2026-07-10. Each reference file has a `## Source` link back to the docs it was drawn from, so it can be refreshed later.
+
+## Quick start
+
+### Install
+
+```bash
+git clone https://github.com/Space-C0wboy/OpenCTI-MCP-Server.git
+cd OpenCTI-MCP-Server
+uv venv
+uv pip install -e ".[dev]"
+```
+
+Or with plain `pip`:
+
+```bash
+pip install -e .
+```
+
+### Get an API token
+
+In OpenCTI, open your profile menu → **API access**, then copy your personal access token.
+
+### Configuration
+
+Configuration is read from environment variables, or from a `.env` file in the working directory (either a standard `KEY=value` dotenv file or a JSON-style fragment). OS environment variables always take precedence over the file.
+
+| Variable | Required | Default | Description |
+| --- | :---: | --- | --- |
+| `OPENCTI_URL` | Yes | — | Base URL of your OpenCTI instance |
+| `OPENCTI_TOKEN` | Yes | — | OpenCTI API token |
+| `OPENCTI_READ_ONLY` | No | `true` | When `true`, hides all write tools and blocks mutations |
+| `OPENCTI_TIMEOUT` | No | `30` | Request timeout in seconds |
+| `OPENCTI_SSL_VERIFY` | No | `true` | Verify TLS certificates |
+| `LOG_LEVEL` | No | `INFO` | Logging verbosity |
+| `MCP_HTTP_HOST` | No | `127.0.0.1` | Bind host when using `--transport http` |
+| `MCP_HTTP_PORT` | No | `8765` | Bind port when using `--transport http` |
+
+### Run
+
+Stdio (default, for editor/IDE integrations):
+
+```bash
+uv run opencti-mcp
+```
+
+HTTP transport:
+
+```bash
+uv run opencti-mcp --transport http --host 127.0.0.1 --port 8765
+```
+
+## Read-only mode
+
+`OPENCTI_READ_ONLY` defaults to `true`. In read-only mode, only list/get tools and `markings_list`/`markings_get` are registered — no `*_create`, `*_update`, or `*_delete` tool is available for any domain, and `graphql_query` raises an error if the query document contains a `mutation`. Set `OPENCTI_READ_ONLY=false` to register the write tools and allow `graphql_query` to run mutations.
+
+## Editor integration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "opencti": {
+      "command": "uv",
+      "args": ["--directory", "/absolute/path/to/OpenCTI-MCP-Server", "run", "opencti-mcp"],
+      "env": {
+        "OPENCTI_URL": "https://your-opencti-instance.example.com/",
+        "OPENCTI_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add opencti -- uv --directory /absolute/path/to/OpenCTI-MCP-Server run opencti-mcp
+```
+
+## Example prompts
+
+- "List the 10 most recent indicators."
+- "Search reports mentioning 'Emotet'."
+- "Show me the MITRE ATT&CK technique T1059."
+- "Create an IPv4 observable for 1.2.3.4." (requires `OPENCTI_READ_ONLY=false`)
+- "Which threat actors are linked to intrusion set APT29?"
+- "Get the full detail on case CASE-ID, including its labels and markings."
+- "What are the 10 most recent reports?"
+- "Is 1.2.3.4 in OpenCTI?"
+- "What is this threat actor related to?"
+- "Search across everything for 'Emotet'."
+- "Are our OpenCTI connectors healthy?"
+- "Export this report as a STIX bundle."
+- "List the groups in OpenCTI."
+- "Add the victim organization 'Acme Corp' to OpenCTI." (requires `OPENCTI_READ_ONLY=false`)
+- "Create an individual identity for John Doe with a description."
+
+## Development
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Support
+
+This is a community-maintained project provided as-is, with no guaranteed support SLA. Issues and pull requests are welcome.