Skip to content

Overview

MCP OTX: threat intelligence for AI agents. Pulses, indicators, passive DNS and malware analysis from AlienVault OTX over the Model Context Protocol.

PyPI version CI License: MIT Python 3.10 or newer MCP Registry

Quickstart · Tools · HTTP · Security · Troubleshooting · Docs

mcp-otx is an MCP server that gives AI agents access to AlienVault OTX (Open Threat Exchange, now LevelBlue). Hand your agent an IP, domain, file hash, URL or CVE, or a malware family or adversary to research, and get back what the OTX community knows: pulses, reputation, passive DNS, whois, sandbox analysis and related indicators.

Note

Independent project, not affiliated with AlienVault or LevelBlue. You need your own OTX API key; a free account is enough.

Highlights

  • Full API coverage. 29 tools across pulses, indicators, users, subscriptions and URL submissions, plus resource templates for pulses and indicators.
  • One-call indicator enrichment. Every OTX indicator type (IPv4, IPv6, domain, hostname, file hash, URL, CVE) and detail section: reputation, geo, passive DNS, malware, whois, URL lists, HTTP scans, sandbox analysis.
  • Read-only by default. The 9 tools that change your OTX account only appear with --read-write.
  • Context-sized output. Large OTX objects are summarized and capped, with the API's total counts kept, so one lookup doesn't fill the model's context.
  • Safe HTTP. stdio for desktop clients, plus streamable HTTP with bearer-token auth. The server refuses to listen on a network-facing address without a token.
  • Tested. Unit tests against a mocked OTX API run in CI on Python 3.10 to 3.13.

How it works

flowchart LR
    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-otx"]
    S -->|"HTTPS + X-OTX-API-KEY"| O["OTX DirectConnect API"]
    O -->|"JSON"| S
    S -->|"summarized, capped JSON"| A

Quickstart

Requirements: Python 3.10 or newer, uv (or pip), and an OTX API key.

# Claude Code
claude mcp add --transport stdio --env OTX_API_KEY=your-key otx -- uvx otx-mcp

# Codex CLI
codex mcp add otx --env OTX_API_KEY=your-key -- uvx otx-mcp

# Gemini CLI
gemini mcp add -e OTX_API_KEY=your-key otx uvx otx-mcp

With pip: pip install otx-mcp, then use the command otx-mcp. For Claude Desktop, VS Code, Cline, Docker and running from source, see Connect a client.

Then ask your agent: "What does OTX know about 8.8.8.8, and are there recent pulses about Emotet?" More prompts are in example workflows.

Tools

20 read tools, plus 9 write tools with --read-write. Full parameters and real sample output are in the tool reference.

Area Read tools Write tools (--read-write)
Search search_pulses, search_users
Pulses get_pulse_details, get_pulse_indicators, get_related_pulses, search_related_pulses, list_pulse_activity, list_subscribed_pulses, get_subscribed_pulse_ids, get_pulse_events create_pulse, subscribe_pulse, unsubscribe_pulse
Indicators get_indicator_details, validate_indicator, list_indicator_types, export_indicators
Users get_user, get_current_user, list_user_pulses, list_my_pulses subscribe_user, unsubscribe_user, follow_user, unfollow_user
Submissions list_submitted_urls, list_submitted_files submit_url, submit_urls

Resource templates: otx://pulse/{pulse_id} and otx://indicator/{type}/{value}.

HTTP transport

stdio is the default. For remote or web clients, run streamable HTTP:

OTX_API_KEY=your-key uvx otx-mcp --transport streamable-http
# → http://127.0.0.1:8000/mcp

To listen on a network-facing address, set a bearer token. Clients must then send Authorization: Bearer <token>:

OTX_API_KEY=your-key OTX_MCP_BEARER_TOKEN=a-long-random-secret \
  uvx otx-mcp --transport streamable-http --host 0.0.0.0

docker build -t mcp-otx .
docker run --rm -p 127.0.0.1:8000:8000 -e OTX_API_KEY=your-key \
  -e OTX_MCP_BEARER_TOKEN=a-long-random-secret \
  -e OTX_MCP_TRANSPORT=streamable-http -e OTX_MCP_HOST=0.0.0.0 mcp-otx

OTX is slow on some endpoints (passive DNS and subscriptions can take 20 to 60 s), so give remote clients a long read timeout (120 s works).

Configuration

Variable CLI flag Default Description
OTX_API_KEY (required) Your OTX API key. Also read from .env
OTX_API_BASE https://otx.alienvault.com/api/v1 API root (for testing)
OTX_MCP_TRANSPORT --transport stdio stdio, streamable-http or sse
OTX_MCP_HOST --host 127.0.0.1 HTTP bind address
OTX_MCP_PORT --port 8000 HTTP port
OTX_MCP_READ_WRITE --read-write off 1 exposes the account-changing tools
OTX_MCP_BEARER_TOKEN off Require Authorization: Bearer <token> on HTTP
--allow-remote off Allow a network-facing bind without a token (not recommended)
--json-response off Plain JSON instead of SSE streams (streamable HTTP)
--stateless-http off A new session per request (streamable HTTP)

Security

Warning

The server acts as your OTX account. Keep it read-only unless you need the write tools, and never expose HTTP without a bearer token and TLS.

  • Read-only by default. Pulse creation, subscriptions, follows and URL submissions need --read-write. Editing or deleting pulses isn't exposed as a tool at all.
  • Untrusted content. Pulse and indicator descriptions are written by the OTX community. The server tells the model to treat them as data, not instructions.
  • The API key is sent only to the OTX API, in a header.

Details are in the security model. Report vulnerabilities privately; see SECURITY.md.

Troubleshooting

  • 403 "Authentication required": the API key is wrong. get_current_user shows which account a key belongs to.
  • A write tool is missing: start the server with --read-write.
  • Timeouts: passive DNS and subscription calls can take up to 60 s. Raise your client's tool timeout.

More in the troubleshooting guide.

Development

git clone https://github.com/w0h1v/mcp-otx && cd mcp-otx
uv venv && uv pip install -e ".[dev]"
.venv/bin/python -m pytest    # mocked OTX API, no key or network

See CONTRIBUTING.md and the changelog.

License

MIT. See LICENSE.