opencti-mcp
Allows triggering VirusTotal enrichment for indicators via the trigger_enrichment tool.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opencti-mcp Search for threat actor APT29 and show recent indicators."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This repository has been retired. It is no longer maintained.
This package is now part of the AppliedIR/sift-mcp monorepo.
Documentation: appliedir.github.io/aiir
OpenCTI MCP Server
An MCP (Model Context Protocol) server providing comprehensive threat intelligence access to OpenCTI for Claude Code and other MCP clients.
Note: Validate and harden appropriately for your environment before production use.
Installation Options
Option A: As Part of Claude-IR (Recommended)
This MCP is designed as a component of the Claude-IR AI-assisted incident response workstation.
git clone https://github.com/scriptedstatement/claude-ir.git
cd claude-ir
./setup.sh
claudeBenefits of Claude-IR installation:
Guided setup with component selection
Pre-configured MCP integration
Works alongside forensic-rag-mcp (knowledge search) and windows-triage-mcp (file validation)
Forensic discipline rules and investigation workflows
Note: This MCP requires an OpenCTI instance. See SETUP.md for guidance on connecting to or deploying OpenCTI.
Option B: Standalone Installation
Use standalone when you only need threat intelligence lookups without the full IR workstation.
git clone https://github.com/scriptedstatement/opencti-mcp.git
cd opencti-mcp
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install
pip install -e .
# Configure (requires OpenCTI instance - see SETUP.md)
export OPENCTI_TOKEN="your-api-token"
export OPENCTI_URL="http://localhost:8080" # Local Docker
# export OPENCTI_URL="https://opencti.example.com" # Remote/cloud
# Run server
python -m opencti_mcpFor OpenCTI setup guidance: See SETUP.md
Related MCP server: Cooper Cyber Coffee OpenCTI MCP Server
Features
Search Operations (32 tools, 28 visible in read-only mode)
Category | Tools | Description |
Unified Search |
| Search across all entity types |
Threats |
| APT groups, campaigns |
Arsenal |
| Malware, tools, CVEs |
Techniques |
| MITRE ATT&CK, mitigations |
Observations |
| IOCs, detection events |
Events |
| Security incidents |
Analysis |
| Reports, groupings, notes |
Entities |
| Organizations, industries |
Locations |
| Countries, regions, cities |
Infrastructure |
| C2, hosting, botnets |
Entity Operations
Tool | Description |
| Get full IOC context with relationships |
| Look up file hash (MD5/SHA1/SHA256) |
| Get any entity by ID |
| Get entity relationships |
| Get indicators from last N days |
Write Operations (requires OPENCTI_READ_ONLY=false)
Tool | Description |
| Create new IOC |
| Add analyst note to entities |
| Record detection event |
| Trigger VirusTotal/Shodan enrichment |
System Operations
Tool | Description |
| Check OpenCTI connectivity |
| List enrichment connectors |
| View adaptive metrics and recommendations |
| Force reconnection (clears caches, resets circuit breaker) |
| View response cache statistics |
Advanced Filtering
All search tools support advanced filtering:
{
"query": "APT29",
"limit": 10,
"offset": 0,
"labels": ["tlp:amber", "apt"],
"confidence_min": 70,
"created_after": "2024-01-01",
"created_before": "2024-12-31"
}Configuration
Settings are loaded via Config.load() classmethod (config.py) with SecretStr token protection and helper parsers for typed env vars.
Environment Variables
Variable | Default | Description |
|
| OpenCTI instance URL (use |
| - | API token (required) |
|
| Disable write operations |
|
| Request timeout in seconds |
|
| Maximum results per query |
|
| Retry attempts for failures |
|
| Initial retry delay (seconds) |
|
| Maximum retry delay (seconds) |
|
| Verify SSL certificates (set |
|
| Failures before circuit opens |
|
| Seconds before circuit recovery |
| - | Custom observable types (comma-separated) |
| - | Custom pattern types (comma-separated) |
|
| Log format: "json" or "text" |
Feature Flags
Control optional features via environment variables (prefix: FF_):
Variable | Default | Description |
|
| Test API connectivity on server start |
|
| Cache search results (reduces API calls) |
|
| Return cached results when service unavailable |
|
| Cache "not found" results |
Token Configuration
Option 1: Environment variable (recommended for production)
export OPENCTI_TOKEN="your-api-token"Option 2: Token file
mkdir -p ~/.config/opencti-mcp
echo "your-api-token" > ~/.config/opencti-mcp/token
chmod 600 ~/.config/opencti-mcp/tokenOption 3: .env file (development)
OPENCTI_TOKEN=your-api-tokenCustom Types for Extended OpenCTI
If your OpenCTI instance has custom observable types or pattern types (e.g., proprietary IOC formats, additional detection languages), configure them via environment variables:
# Add custom observable types (case-sensitive, comma-separated)
export OPENCTI_EXTRA_OBSERVABLE_TYPES="Internal-Host,Cloud-Resource,Custom-IOC"
# Add custom pattern types (case-insensitive, comma-separated)
export OPENCTI_EXTRA_PATTERN_TYPES="osquery,kql,custom-sig"These extend the built-in allow-lists without removing standard STIX types.
Claude Code Configuration
Add to your project-local .mcp.json (or see the parent claude-ir project for automated setup):
{
"mcpServers": {
"opencti": {
"command": "/path/to/venv/bin/python",
"args": ["-m", "opencti_mcp"],
"cwd": "/path/to/opencti-mcp",
"env": {
"PYTHONPATH": "/path/to/opencti-mcp/src",
"OPENCTI_TOKEN": "your-api-token",
"OPENCTI_URL": "http://localhost:8080",
"OPENCTI_READ_ONLY": "true",
"OPENCTI_SSL_VERIFY": "true"
}
}
}
}Project Structure
opencti-mcp/
├── src/opencti_mcp/
│ ├── __init__.py # Package exports
│ ├── __main__.py # Entry point (with startup validation)
│ ├── server.py # MCP server (32 tools)
│ ├── client.py # OpenCTI API client (with caching)
│ ├── config.py # Configuration management
│ ├── validation.py # Input validation
│ ├── errors.py # Error hierarchy
│ ├── logging.py # Structured logging
│ ├── adaptive.py # Network metrics
│ ├── cache.py # TTL-based response caching
│ └── feature_flags.py # Feature flag management
├── tests/ # Test suite (1530 tests)
├── docs/ # Documentation
├── README.md # This file
├── CLAUDE.md # Development guide
├── IMPLEMENTATION.md # Technical architecture
└── pyproject.toml # Package configurationDevelopment
Run Tests
# Install dev dependencies
pip install -e ".[dev]"
# Run all tests
pytest
# With coverage
pytest --cov=opencti_mcp --cov-report=html
# Type checking
mypy src/opencti_mcpTest with MCP Inspector
npx @anthropic/mcp-inspector python -m opencti_mcpKey Commands
# Run MCP server
python -m opencti_mcp
# Test connection (original CLI)
python opencti_query.py "APT29" --type threat_actor
# Quick health check
python -c "from opencti_mcp import OpenCTIClient, Config; c = OpenCTIClient(Config.load()); print('OK' if c.is_available() else 'FAIL')"Production Considerations
Local Docker vs Remote/Cloud
The default OPENCTI_URL=http://localhost:8080 matches OpenCTI's standard Docker deployment, where the platform serves HTTP on port 8080. This is correct for local instances — traffic never leaves the machine.
For remote or cloud instances, use HTTPS. OpenCTI supports TLS either natively (APP__HTTPS_CERT__* env vars) or via a reverse proxy (Nginx, Caddy, Traefik) — the reverse proxy approach is more common in production.
Recommended Settings for Remote/Cloud Instances
export OPENCTI_URL=https://opencti.example.com # HTTPS for remote
export OPENCTI_TIMEOUT=120 # Higher for cloud (default 60 may be tight for complex queries)
export OPENCTI_MAX_RETRIES=3 # Retry on transient failures
export OPENCTI_SSL_VERIFY=true # Always for production (false only for self-signed certs)
export OPENCTI_READ_ONLY=true # Unless writes neededCloud users: If you experience timeouts or circuit breaker trips, increase
OPENCTI_TIMEOUTto 120-180. Complex threat intel queries on remote instances can take 60+ seconds under load.
Adaptive Metrics
Use get_network_status tool to view:
Latency statistics (P50/P95/P99)
Success rates
Circuit breaker state
Recommended timeout/retry settings
Requirements
Python 3.10+
OpenCTI 6.x instance
pycti 6.x
mcp 1.x
Acknowledgments
Architecture and direction by Steve Anson. Implementation by Claude Code (Anthropic).
License
MIT
Available Tools
28 toolsforce_reconnectA
Force reconnection to OpenCTI server. Clears health cache, resets circuit breaker, and attempts fresh connection. Use after configuration changes or to recover from persistent errors.
Inputs: no named parameters.
get_cache_statsA
Get cache statistics including hit rates, sizes, and evictions. Useful for debugging and performance tuning.
Inputs: no named parameters.
get_entityA
Get full details of any entity by its OpenCTI ID.
Inputs: entity_id (required).
get_healthA
Check OpenCTI server health and connectivity.
Inputs: no named parameters.
get_network_statusA
Get network health metrics and adaptive configuration recommendations. Shows latency statistics (P50/P95/P99), success rates, circuit breaker state, and recommended timeout/retry settings based on observed network conditions.
Inputs: no named parameters.
get_recent_indicatorsB
Get recently added indicators (IOCs) from the last N days.
Inputs: days, limit.
get_relationshipsA
Get relationships for an entity (who uses what, what indicates what, etc.).
Inputs: entity_id (required), limit, direction, relationship_types.
list_connectorsA
List available enrichment connectors (VirusTotal, Shodan, etc.).
Inputs: no named parameters.
lookup_hashC
Look up a file hash (MD5, SHA1, SHA256) in OpenCTI.
Inputs: hash (required).
lookup_iocB
Get full context for a specific IOC (IP, hash, domain, URL) including related threat actors, malware, and MITRE techniques.
Inputs: ioc (required).
search_attack_patternA
Search for MITRE ATT&CK techniques by ID or name.
Inputs: query (required), limit, labels, offset, +2 more.
search_campaignA
Search for threat campaigns by name or keyword.
Inputs: query (required), limit.
search_course_of_actionA
Search for courses of action (mitigations for attack techniques).
Inputs: query (required), limit.
search_groupingB
Search for groupings (analysis containers that group related entities).
Inputs: query (required), limit.
search_incidentC
Search for security incidents.
Inputs: query (required), limit.
search_infrastructureB
Search for infrastructure (C2 servers, hosting, botnets, etc.).
Inputs: query (required), limit, labels, offset, +2 more.
search_locationC
Search for locations (countries, regions, cities).
Inputs: query (required), limit.
search_malwareB
Search for malware families by name or alias.
Inputs: query (required), limit, labels, offset, +3 more.
search_noteC
Search for analyst notes.
Inputs: query (required), limit.
search_observableB
Search for observables (raw technical artifacts: IPs, domains, hashes, emails, etc.).
Inputs: query (required), limit, observable_types.
search_organizationB
Search for organizations (companies, government bodies, etc.).
Inputs: query (required), limit.
search_reportsC
Search for threat intelligence reports.
Inputs: query (required), limit.
search_sectorA
Search for sectors/industries (e.g., 'Energy', 'Healthcare', 'Finance').
Inputs: query (required), limit.
search_sightingA
Search for sightings (detection events where indicators were observed).
Inputs: query (required), limit.
search_threat_actorC
Search for threat actors and APT groups by name or alias.
Inputs: query (required), limit, labels, offset, +3 more.
search_threat_intelA
Search OpenCTI for threat intelligence across all entity types (indicators, threat actors, malware, techniques, CVEs, reports).
Inputs: query (required), limit, labels, offset, +3 more.
search_toolB
Search for tools (legitimate software used maliciously, e.g., PsExec, Mimikatz as a tool).
Inputs: query (required), limit, labels, offset, +2 more.
search_vulnerabilityC
Search for vulnerabilities (CVEs) by ID or keyword.
Inputs: query (required), limit, labels, offset, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Most tools are neatly separated by STIX entity type via the search_<entity> family, so an agent can usually pick the right one. However, search_threat_intel broadly overlaps with every specific search, and lookup_ioc vs. lookup_hash creates ambiguity for hash lookups.
Tool names consistently follow a lowercase snake_case verb_noun structure, with search_<entity> dominating the set. The mix of search, lookup, get, list, and force verbs is mostly predictable, though force_reconnect and the generic search_threat_intel are minor deviations from the clearer noun patterns.
At 28 tools this is on the heavy side, but the count is largely driven by comprehensive coverage of OpenCTI's many STIX entity types. Several operational tools like get_cache_stats and get_network_status add bulk and could be trimmed, yet each search tool has a distinct target.
For a read-only threat intelligence investigation server, the surface is quite complete: it covers major STIX entities, IOC lookup, generic entity details, relationships, recent indicators, and health/connector status. It lacks create/update/delete operations, but the tool names suggest the server is intentionally query-focused, so this is a minor gap rather than a critical one.
Related MCP Connectors
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
Cybersecurity MCP server for URL scanning, threat intelligence, and domain reputation.
Related MCP Servers
- AlicenseBqualityDmaintenanceThis MCP server transforms Claude into a comprehensive security analyst by providing access to 27 security tools across 21 APIs for vulnerability intelligence. It enables users to query multiple sources like NVD, EPSS, CISA KEV, and threat intelligence platforms in parallel to get correlated security insights and risk assessments for CVEs.281,778Apache 2.0
- FlicenseNot gradedqualityCmaintenanceThis MCP server connects Claude Desktop to OpenCTI for AI-augmented threat intelligence analysis, enabling natural language queries and instant, contextualized answers from your threat intelligence database.29-
- AlicenseNot gradedqualityDmaintenanceMCP server that provides condensed and normalized data from OpenCTI to LLMs, enabling lookup of observables, adversaries, and reports with enriched context.16MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server that exposes multiple OSINT tools to AI assistants like Claude, enabling sophisticated reconnaissance and information gathering tasks using industry-standard OSINT tools.250MIT