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

mermaid

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.

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.

OTX

What it does

What it costs