shodan

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

mcp-shodan は、AI エージェントが Shodan API と Shodan CVEDB にアクセスできるようにする MCP サーバーです。IP アドレス、ホスト名、検索クエリ、製品名、または CVE をエージェントに渡すと、アナリストが確認するような情報が返されます。開いているポートやバナー、TLS 証明書、DNS、EPSS と KEV のステータスを含む脆弱性の深刻度などを取得できます。

メモ

独立したプロジェクトであり、Shodan とは提携していません。ご自身の Shodan API キーが必要です。

特長

• ホスト偵察。 任意の IPv4 または IPv6 アドレスについて、開いているポート、製品とバージョン、既知の CVE、TLS 証明書の詳細（フィンガープリント、JARM、JA3S）、クラウドプロバイダー、バナー履歴を取得します。
• デバイス検索。 ページングとファセットによる内訳（国、組織、ポート、脆弱性など）に対応した Shodan クエリ構文に加え、クエリの規模を把握できる無料の件数のみのモードを備えています。
• 脆弱性インテリジェンス。 CVSS v4/v3/v2、EPSS、KEV を含む CVE の詳細を取得します。製品または CPE 別に CVE を検索し、EPSS で並べ替えられます。CVEDB は無料で、検索クレジットを消費しません。
• DNS。 ドメインのサブドメインと DNS レコードに加え、1 回の呼び出しで複数の名前や IP アドレスを正引き・逆引きできます。
• クレジットに配慮。 無料ツールには無料であることが明示され、api_info でプランの残りクレジットを確認できます。
• 2 種類のトランスポート。 デスクトップクライアント向けの stdio と、共有サービス向けの HTTP ストリーミングに対応しています。
• テスト済み。 Shodan API をモックしたユニットテストを、Node 20、22、24 上で CI により実行します。

仕組み

flowchart LR
    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-shodan"]
    S -->|"validate input,<br/>HTTPS + API key"| SH["Shodan REST API"]
    S -->|"HTTPS, no key"| C["Shodan CVEDB"]
    SH -->|"JSON"| S
    C -->|"JSON"| S
    S -->|"structured JSON text"| A

クイックスタート

必要条件： Node.js 20 以降と Shodan API キー。

# Claude Code
claude mcp add --transport stdio --env SHODAN_API_KEY=your-key shodan -- npx -y @burtthecoder/mcp-shodan

# Codex CLI
codex mcp add shodan --env SHODAN_API_KEY=your-key -- npx -y @burtthecoder/mcp-shodan

# Gemini CLI
gemini mcp add -e SHODAN_API_KEY=your-key shodan npx -y @burtthecoder/mcp-shodan

Claude Desktop、VS Code、Smithery、およびソースからの実行については、クライアントの接続を参照してください。

次に、エージェントに「8.8.8.8 では何が公開されていますか？また、CVE-2021-44228 は KEV カタログに掲載されていますか？」と尋ねてみましょう。その他のプロンプトはワークフローの例をご覧ください。

ツール

読み取り専用ツールが11個あります。パラメーターの詳細はツールリファレンスをご覧ください。

グループ	ツール	機能
ネットワーク	ip_lookup	1つのIPについて、ポート、製品、CVE、TLS、位置情報、クラウドを確認します。必要に応じてバナーの履歴も確認できます
	shodan_search	Shodanのクエリ構文を使ってデバイスを検索します。ページングとファセットの内訳にも対応しています
	shodan_count	クエリに一致する件数の合計とファセットの内訳を、結果を表示せずに取得します（無料）
	domain_info	ドメインのサブドメインとDNSレコードを取得します
	dns_lookup	ホスト名をIPに一括で解決します
	reverse_dns_lookup	IPに対応するホスト名を一括で取得します
脆弱性（CVEDB）	cve_lookup	1つのCVEについて、CVSS、EPSS、KEV、参照情報、影響を受けるCPEを取得します
	cpe_lookup	製品名からCPE 2.3識別子を取得します
	cves_by_product	製品またはCPEのCVEを取得します。KEVや日付で絞り込み、EPSSで並べ替えできます
ヘルパー	search_filters	有効な検索フィルターとファセット名を取得します
	api_info	ご利用プランと残りのクエリおよびスキャンのクレジットを確認します

ヒント

クレジット：フィルターを使ったshodan_searchクエリはクエリクレジットを1つ消費します（追加ページごとに1つ追加）。domain_infoは呼び出しごとに1つ消費します。shodan_count、ip_lookup、dns_lookup、reverse_dns_lookup、search_filters、api_info、CVEDBツールは無料です。

HTTPストリーミングトランスポート

デフォルトはstdioです。MCP_TRANSPORT=httpStreamを設定すると、スタンドアロンのHTTPサービスとして実行できます。

MCP_TRANSPORT=httpStream MCP_PORT=3000 SHODAN_API_KEY=your-key node build/index.js

docker build -t mcp-shodan .
docker run -p 127.0.0.1:3000:3000 -e SHODAN_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-shodan

ヘルスチェックは/healthで提供されます。

環境変数

変数	デフォルト	説明
SHODAN_API_KEY	(必須)	Shodan APIキー
MCP_TRANSPORT	stdio	stdioまたはhttpStream
MCP_HOST	localhost	バインドアドレス（httpStreamのみ）。Dockerイメージでは0.0.0.0が設定されます
MCP_PORT	3000	HTTPポート（httpStreamのみ）
MCP_ENDPOINT	/mcp	HTTPエンドポイントのパス（httpStreamのみ）

セキュリティ

警告

HTTPトランスポートには認証機能がありません。ポートはlocalhost上に置くか、認証機能を備えたリバースプロキシの背後に配置してください。そうしないと、アクセス可能な人なら誰でもクエリクレジットを消費できます。

• リクエストを構築する前に、ツールの引数をzodスキーマで検証します。IPは有効なIPv4またはIPv6、ドメインは有効なホスト名、ファセットはname[:count]形式のリストである必要があります。また、CVE IDはCVE-YYYY-NNNNに一致する必要があります。
• APIキーは環境から読み込まれ、api.shodan.ioにのみ送信されます。CVEDBの呼び出しにキーは含まれません。
• 検索した内容はShodanに送信されます。

脆弱性は非公開で報告してください。詳細はSECURITY.mdをご覧ください。

トラブルシューティング

• 401 / 無効なキー： キーの前後にスペースや引用符がないか確認し、クライアントを再起動してください。curl "https://api.shodan.io/api-info?key=$SHODAN_API_KEY"でプランとクレジットを確認できます。
• shodan_searchで403： 検索フィルターの利用には、メンバーシップまたは有料APIプランが必要です。api_infoを実行して、プランとクレジットを確認してください。
• 429： Shodanでは、1秒あたり約1件のリクエストが許可されています。少し待ってから再試行してください。

詳しくはトラブルシューティングガイドをご覧ください。

開発

git clone https://github.com/w0h1v/mcp-shodan && cd mcp-shodan
npm ci
npm test                          # build + unit tests, no key or network
npx fastmcp dev build/index.js    # try tools interactively (needs SHODAN_API_KEY)

CONTRIBUTING.mdと変更履歴をご覧ください。

ライセンス

MITです。LICENSEをご覧ください。