otx

クイックスタート · ツール · HTTP · セキュリティ · トラブルシューティング · ドキュメント

mcp-otx は、AI エージェントが AlienVault OTX（Open Threat Exchange、現在の LevelBlue）にアクセスできる MCP サーバーです。調査対象の IP アドレス、ドメイン、ファイルハッシュ、URL、CVE、マルウェアファミリー、または攻撃者をエージェントに渡すと、OTX コミュニティが把握しているパルス、レピュテーション、パッシブ DNS、WHOIS、サンドボックス分析、関連インジケーターを取得できます。

メモ

独立したプロジェクトであり、AlienVault または LevelBlue とは提携していません。ご自身の OTX API キーが必要です。無料アカウントで十分です。

特長

• API を全面的にカバー。 パルス、インジケーター、ユーザー、サブスクリプション、URL 送信を網羅する 29 個のツールに加え、パルスとインジケーター用のリソーステンプレートを提供します。
• 1 回の呼び出しでインジケーターを強化。 OTX のすべてのインジケータータイプ（IPv4、IPv6、ドメイン、ホスト名、ファイルハッシュ、URL、CVE）と詳細セクション（レピュテーション、位置情報、パッシブ DNS、マルウェア、WHOIS、URL リスト、HTTP スキャン、サンドボックス分析）に対応しています。
• デフォルトは読み取り専用。 OTX アカウントを変更する 9 個のツールは、--read-write を指定した場合にのみ表示されます。
• コンテキストに合わせた出力。 大きな OTX オブジェクトは要約して上限を設け、API の合計件数は保持するため、1 回の検索でモデルのコンテキストが埋まることはありません。
• 安全な HTTP。 デスクトップクライアント向けの stdio に加え、ベアラートークン認証を備えたストリーミング可能な HTTP に対応しています。トークンなしでネットワークに公開されるアドレスをリッスンしようとすると、サーバーは起動を拒否します。
• テスト済み。 モック OTX API を使用したユニットテストを、Python 3.10～3.13 の CI で実行します。

動作の仕組み

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

クイックスタート

要件： Python 3.10 以降、uv（または pip）、OTX API キー。

# 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

pip を使う場合：pip install otx-mcp を実行し、コマンド otx-mcp を使用します。Claude Desktop、VS Code、Cline、Docker、ソースからの実行については、クライアントの接続をご覧ください。

続けて、エージェントに 「OTX は 8.8.8.8 について何を把握していますか？ Emotet に関する最近のパルスはありますか？」 と尋ねてみましょう。その他のプロンプトはワークフローの例をご覧ください。

ツール

読み取りツールが20個、--read-write を指定すると書き込みツールが9個利用できます。すべてのパラメーターと実際の出力例については、ツールリファレンスを参照してください。

領域	読み取りツール	書き込みツール（--read-write）
検索	search_pulses、search_users
Pulse	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
インジケーター	get_indicator_details、validate_indicator、list_indicator_types、export_indicators
ユーザー	get_user、get_current_user、list_user_pulses、list_my_pulses	subscribe_user、unsubscribe_user、follow_user、unfollow_user
提出	list_submitted_urls、list_submitted_files	submit_url、submit_urls

リソーステンプレート：otx://pulse/{pulse_id} および otx://indicator/{type}/{value}。

HTTP トランスポート

デフォルトは stdio です。リモートクライアントやウェブクライアントの場合は、ストリーム可能な HTTP を実行します。

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

ネットワークに公開するアドレスで待ち受けるには、ベアラートークンを設定します。その場合、クライアントは 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 は一部のエンドポイント（パッシブ DNS とサブスクリプション）で応答が遅く、20～60秒かかることがあるため、リモートクライアントには長い読み取りタイムアウトを設定してください（120秒が適切です）。

設定

変数	CLI フラグ	デフォルト	説明
OTX_API_KEY		(必須)	OTX API キーです。.env からも読み込まれます
OTX_API_BASE		https://otx.alienvault.com/api/v1	API ルート（テスト用）
OTX_MCP_TRANSPORT	--transport	stdio	stdio、streamable-http、または sse
OTX_MCP_HOST	--host	127.0.0.1	HTTP バインドアドレス
OTX_MCP_PORT	--port	8000	HTTP ポート
OTX_MCP_READ_WRITE	--read-write	オフ	1 にすると、アカウントを変更するツールが利用可能になります
OTX_MCP_BEARER_TOKEN		オフ	HTTP で Authorization: Bearer <token> を必須にします
	--allow-remote	オフ	トークンなしでネットワークに公開するバインドを許可します（非推奨）
	--json-response	オフ	SSE ストリームの代わりにプレーンな JSON を返します（ストリーム可能な HTTP）
	--stateless-http	オフ	リクエストごとに新しいセッションを作成します（ストリーム可能な HTTP）

セキュリティ

警告

サーバーはお使いの OTX アカウントとして動作します。書き込みツールが必要な場合を除き、読み取り専用にしてください。また、ベアラートークンと TLS なしで HTTP を公開しないでください。

• デフォルトでは読み取り専用です。 Pulse の作成、サブスクリプション、フォロー、URL の提出には --read-write が必要です。Pulse の編集や削除は、そもそもツールとして公開されていません。
• 信頼できないコンテンツ。 Pulse とインジケーターの説明は OTX コミュニティによって書かれています。サーバーは、モデルに対して説明を指示ではなくデータとして扱うよう伝えます。
• API キーはヘッダーに含めて OTX API にのみ送信されます。

詳細はセキュリティモデルを参照してください。脆弱性は非公開で報告してください。SECURITY.mdを参照してください。

トラブルシューティング

• **403 "Authentication required"：**API キーが正しくありません。get_current_user を使うと、キーがどのアカウントに属するか確認できます。
• 書き込みツールが見つからない場合：--read-write を指定してサーバーを起動してください。
• **タイムアウト：**パッシブ DNS とサブスクリプションの呼び出しには最大60秒かかることがあります。クライアントのツールタイムアウトを延長してください。

詳細はトラブルシューティングガイドを参照してください。

開発

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

CONTRIBUTING.mdと変更履歴を参照してください。

ライセンス

MIT。LICENSEを参照してください。