English Français العربية

io.github.w0h1v/otx

Official registry Search and web

MCP server for AlienVault OTX threat intelligence: indicators, pulses, search, and users.

Source code Documentation

What can you do with io.github.w0h1v/otx?

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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package otx-mcp
Claude Code 
claude mcp add otx -e 'OTX_API_KEY=<your otx_api_key>' -e 'OTX_MCP_READ_WRITE=<OTX_MCP_READ_WRITE>' -- uvx otx-mcp==1.2.0
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "otx": {
            "command": "uvx",
            "args": [
                "otx-mcp==1.2.0"
            ],
            "env": {
                "OTX_API_KEY": "<your otx_api_key>",
                "OTX_MCP_READ_WRITE": "<OTX_MCP_READ_WRITE>"
            }
        }
    }
}

Environment variables

  • OTX_API_KEY required secret Your AlienVault OTX API key
  • OTX_MCP_READ_WRITE Set to 1 to expose account-mutating tools (create/subscribe/follow/submit). Read-only by default.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Highlights
  2. How it works
  3. Quickstart
  4. Tools
  5. HTTP transport
  6. Security
  7. Troubleshooting
  8. Development
  9. License

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.

AreaRead toolsWrite tools (--read-write)
Searchsearch_pulses, search_users
Pulsesget_pulse_details, get_pulse_indicators, get_related_pulses, search_related_pulses, list_pulse_activity, list_subscribed_pulses, get_subscribed_pulse_ids, get_pulse_eventscreate_pulse, subscribe_pulse, unsubscribe_pulse
Indicatorsget_indicator_details, validate_indicator, list_indicator_types, export_indicators
Usersget_user, get_current_user, list_user_pulses, list_my_pulsessubscribe_user, unsubscribe_user, follow_user, unfollow_user
Submissionslist_submitted_urls, list_submitted_filessubmit_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
VariableCLI flagDefaultDescription
OTX_API_KEY(required)Your OTX API key. Also read from .env
OTX_API_BASEhttps://otx.alienvault.com/api/v1API root (for testing)
OTX_MCP_TRANSPORT--transportstdiostdio, streamable-http or sse
OTX_MCP_HOST--host127.0.0.1HTTP bind address
OTX_MCP_PORT--port8000HTTP port
OTX_MCP_READ_WRITE--read-writeoff1 exposes the account-changing tools
OTX_MCP_BEARER_TOKENoffRequire Authorization: Bearer <token> on HTTP
--allow-remoteoffAllow a network-facing bind without a token (not recommended)
--json-responseoffPlain JSON instead of SSE streams (streamable HTTP)
--stateless-httpoffA 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.

Frequently asked questions

What is io.github.w0h1v/otx?

MCP server for AlienVault OTX threat intelligence: indicators, pulses, search, and users.

How do I install io.github.w0h1v/otx?

It runs on your machine. In Claude Code: claude mcp add otx -e 'OTX_API_KEY=<your otx_api_key>' -e 'OTX_MCP_READ_WRITE=<OTX_MCP_READ_WRITE>' -- uvx otx-mcp==1.2.0. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.w0h1v/otx need an API key?

Yes. It expects OTX_API_KEY, which you set in its configuration.

Is io.github.w0h1v/otx open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.w0h1v/otx?

It is published by w0h1v. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.