[!IMPORTANT] 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
claude

Benefits 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_mcp

For OpenCTI setup guidance: See SETUP.md

Features

Search Operations (32 tools, 28 visible in read-only mode)

| Category | Tools | Description | |----------|-------|-------------| | Unified Search | search_threat_intel | Search across all entity types | | Threats | search_threat_actor, search_campaign | APT groups, campaigns | | Arsenal | search_malware, search_tool, search_vulnerability | Malware, tools, CVEs | | Techniques | search_attack_pattern, search_course_of_action | MITRE ATT&CK, mitigations | | Observations | search_observable, search_sighting | IOCs, detection events | | Events | search_incident | Security incidents | | Analysis | search_reports, search_grouping, search_note | Reports, groupings, notes | | Entities | search_organization, search_sector | Organizations, industries | | Locations | search_location | Countries, regions, cities | | Infrastructure | search_infrastructure | C2, hosting, botnets |

Entity Operations

| Tool | Description | |------|-------------| | lookup_ioc | Get full IOC context with relationships | | lookup_hash | Look up file hash (MD5/SHA1/SHA256) | | get_entity | Get any entity by ID | | get_relationships | Get entity relationships | | get_recent_indicators | Get indicators from last N days |

Write Operations (requires OPENCTI_READ_ONLY=false)

| Tool | Description | |------|-------------| | create_indicator | Create new IOC | | create_note | Add analyst note to entities | | create_sighting | Record detection event | | trigger_enrichment | Trigger VirusTotal/Shodan enrichment |

System Operations

| Tool | Description | |------|-------------| | get_health | Check OpenCTI connectivity | | list_connectors | List enrichment connectors | | get_network_status | View adaptive metrics and recommendations | | force_reconnect | Force reconnection (clears caches, resets circuit breaker) | | get_cache_stats | 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_URL | http://localhost:8080 | OpenCTI instance URL (use https:// for remote) | | OPENCTI_TOKEN | - | API token (required) | | OPENCTI_READ_ONLY | true | Disable write operations | | OPENCTI_TIMEOUT | 60 | Request timeout in seconds | | OPENCTI_MAX_RESULTS | 100 | Maximum results per query | | OPENCTI_MAX_RETRIES | 3 | Retry attempts for failures | | OPENCTI_RETRY_DELAY | 1.0 | Initial retry delay (seconds) | | OPENCTI_RETRY_MAX_DELAY | 30.0 | Maximum retry delay (seconds) | | OPENCTI_SSL_VERIFY | true | Verify SSL certificates (set false for self-signed) | | OPENCTI_CIRCUIT_THRESHOLD | 5 | Failures before circuit opens | | OPENCTI_CIRCUIT_TIMEOUT | 60 | Seconds before circuit recovery | | OPENCTI_EXTRA_OBSERVABLE_TYPES | - | Custom observable types (comma-separated) | | OPENCTI_EXTRA_PATTERN_TYPES | - | Custom pattern types (comma-separated) | | OPENCTI_LOG_FORMAT | json | Log format: "json" or "text" |

Feature Flags

Control optional features via environment variables (prefix: FF_):

| Variable | Default | Description | |----------|---------|-------------| | FF_STARTUP_VALIDATION | true | Test API connectivity on server start | | FF_RESPONSE_CACHING | false | Cache search results (reduces API calls) | | FF_GRACEFUL_DEGRADATION | true | Return cached results when service unavailable | | FF_NEGATIVE_CACHING | true | Cache "not found" results |

Token Configuration

Option 1: Environment variable (recommended for production) ``bash export OPENCTI_TOKEN="your-api-token" ``

Option 2: Token file ``bash mkdir -p ~/.config/opencti-mcp echo "your-api-token" > ~/.config/opencti-mcp/token chmod 600 ~/.config/opencti-mcp/token ``

Option 3: .env file (development) `` OPENCTI_TOKEN=your-api-token ``

Custom 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 configuration

Development

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_mcp

Test with MCP Inspector

npx @anthropic/mcp-inspector python -m opencti_mcp

Key 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 needed

Cloud users: If you experience timeouts or circuit breaker trips, increase OPENCTI_TIMEOUT to 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