OpenCTI MCP Server

A Model Context Protocol 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

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 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/ 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 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

From PyPI (recommended):

uv tool install opencti-mcp        # installs the `opencti-mcp` command

Or with pip, or run it without installing:

pip install opencti-mcp
uvx --from opencti-mcp opencti-mcp --help   # run ad hoc, no install

From source (for development):

git clone https://github.com/Space-C0wboy/OpenCTI-MCP-Server.git
cd OpenCTI-MCP-Server
uv venv
uv pip install -e ".[dev]"

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.

Run

Stdio (default, for editor/IDE integrations):

opencti-mcp                 # if installed via `uv tool install` / `pip`
# from source: uv run opencti-mcp

HTTP transport:

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 (uses uvx, no install or local path needed):

{
  "mcpServers": {
    "opencti": {
      "command": "uvx",
      "args": ["--from", "opencti-mcp", "opencti-mcp"],
      "env": {
        "OPENCTI_URL": "https://your-opencti-instance.example.com/",
        "OPENCTI_TOKEN": "your-api-token"
      }
    }
  }
}

If you installed it (uv tool install opencti-mcp / pip install opencti-mcp), use "command": "opencti-mcp" with "args": [] instead. To run from a source checkout, use "command": "uv", "args": ["--directory", "/absolute/path/to/OpenCTI-MCP-Server", "run", "opencti-mcp"].

Claude Code

claude mcp add opencti -- uvx --from opencti-mcp 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

uv run pytest
uv run ruff check .

License

MIT — see LICENSE.

Support

This is a community-maintained project provided as-is, with no guaranteed support SLA. Issues and pull requests are welcome.