virustotal

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

mcp-virustotal は、AI エージェントが VirusTotal v3 API を利用できるようにする MCP サーバーです。ハッシュ、URL、IP、またはドメインをエージェントに渡すと、検出レポートに加えて、アナリストが調査でたどる関連情報（接続先ホスト、ドロップされたファイル、名前解決情報、脅威アクター）が返されます。

メモ

VirusTotal または Google とは無関係の独立したプロジェクトです。ご自身の VirusTotal API キーが必要です。

主な特長

• 関連情報付きレポート。 ファイル、URL、IP、ドメインのレポートでは、クォータを節約するため、主要な関連情報を 1 回のバッチ ?relationships= 呼び出しで取得します。
• キャッシュを優先。 get_url_report はキャッシュされた VirusTotal レポートを返し、キャッシュにない場合にのみスキャンを送信します。
• 調査用ツール。 VTI 形式の修飾子（type:peexe positives:5+）を使ったコーパス検索、サンドボックスの挙動の統合サマリー、脅威アクターおよびマルウェアファミリーのコレクションに対応しています。
• 関連情報の全ページ取得。 ファイル、URL、IP、ドメインを対象に、100 種類以上の関連情報をカーソルページネーションで取得できます。
• 2 種類のトランスポート。 デスクトップクライアント向けの stdio と、共有サービス向けの HTTP ストリーミングに対応しています。
• テスト済み。 フォーマッターと API レイヤーの単体テストを、Node 20、22、24 上で CI により実行します。

仕組み

flowchart LR
    A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-virustotal"]
    S -->|"validate input,<br/>HTTPS + API key"| V["VirusTotal v3 API"]
    V -->|"JSON"| S
    S -->|"formatted report text"| A

クイックスタート

要件： Node.js 20 以降と VirusTotal API キー。

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

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

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

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

次に、エージェントに 「SHA-256 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f（EICAR テストファイル）を調べ、そこからドロップされるものと接続先を表示して。」 と尋ねてください。

ツール

ツールは 11 個あります。パラメーターと関連情報の一覧は、ツールリファレンスを参照してください。

グループ	ツール
レポート（関連情報付き）	get_file_report、get_url_report、get_ip_report、get_domain_report
関連情報のページ取得	get_file_relationship、get_url_relationship、get_ip_relationship、get_domain_relationship
検索と調査	search_vt、get_file_behaviour_summary、get_collection

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

デフォルトは stdio です。MCP_TRANSPORT=httpStream を設定すると、単独の HTTP サービスを実行できます。

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

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

/health でヘルスチェックを利用できます。

環境変数

変数	デフォルト	説明
VIRUSTOTAL_API_KEY	(必須)	VirusTotal 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 上に置くか、認証機能を備えたリバースプロキシの背後に配置してください。そうしないと、アクセス可能な人なら誰でも API の利用枠を消費できます。

• リクエストを作成する前に、ツールの引数を zod スキーマで検証します。
• API キーは環境変数から読み取られ、VirusTotal にのみ送信されます。
• 検索では、インジケーターが VirusTotal に送信されます。キャッシュミス時の URL スキャンでは、その URL を送信して分析します。

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

トラブルシューティング

• **API キーが正しくない場合：**キーは通常、空白や引用符を含まない 64 文字です。設定を変更した後は、クライアントを再起動してください。
• **429 エラー：**パブリックプランでは、1 分あたり 4 件のリクエストが許可されています。
• **ログ：**パッケージディレクトリ内の logs/mcp-virustotal-server.log。

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

開発

git clone https://github.com/w0h1v/mcp-virustotal && cd mcp-virustotal
npm ci
npm test                                  # build + unit tests, no key or network
VIRUSTOTAL_API_KEY=your-key npm run smoke # all 11 tools against the real API

スモークテストでは、パブリックプランの制限に合わせて呼び出しの間隔を 20 秒空けます。1 日あたり数件の検索に制限された無料プランには適していません。CONTRIBUTING.md と変更履歴をご覧ください。

ライセンス

MIT。LICENSEをご覧ください。