otx-mcp 1.2.0

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.

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.

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

Security

• 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.