wireshark-mcp

---

これは何ですか？

tshark（および任意の Wireshark スイートツール）を、構造化された分析インターフェースに統合する MCP サーバーです。Claude Desktop、Claude Code、Cursor、VS Code、その他 18 以上の MCP クライアントで利用できます。

You:    "Find all DNS queries going to suspicious domains in this capture."
Claude: [calls wireshark_extract_dns_queries → wireshark_detect_dns_tunnel]
        "Found repeated high-entropy DNS queries consistent with tunneling: ..."

バージョン 4.0 の新機能

• キャプチャインデックス。 オプションの [index] エクストラを使うと、wireshark_index がキャプチャを一度だけ解析し、ローカルの DuckDB ファイルに保存します。その後の wireshark_aggregate と wireshark_extract_fields の呼び出しでは、tshark と同一の回答を返します。1 GB のデータでは 408 倍高速で、10 GB では tshark の処理が停止する質問にも回答できます。読み取り専用 SQL、キャプチャセット、初回検出タイムライン、キャプチャまたはウィンドウの差分、Parquet エクスポートにも対応します。キャプチャインデックスを参照してください。
• 統一された検出結果の形式。 すべての検出ツールは、安定した ID、証拠アンカー、再確認用のネイティブな tshark コマンド、候補となる ATT&CK 手法を含む data.findings を返します。
• ケースファイル。 wireshark_case は、キャプチャ、記録済みの結果、検出事項、アナリストの判定を JSON ケースファイルに保存するため、長期にわたる調査もコンテキストのリセット後に引き継げます。検出結果とケースを参照してください。

3.x からのアップグレードに設定変更は不要です。wireshark_detect_beaconing、wireshark_detect_exfiltration、wireshark_detect_protocol_anomalies、wireshark_detect_arp_spoofing、wireshark_yara_scan、または wireshark_quick_analysis のプレーンテキスト出力を解析していたスクリプトは、代わりに JSON エンベロープを読み取る必要があります。詳細については、4.0.0 の変更履歴を参照してください。

---

インストール

Claude Code / Codex プラグイン経由

前提条件：uv と Wireshark CLI（tshark）。プラグインにはこのプロジェクトと 2 つのスキルが含まれます。クライアントは stdio 経由で uv を使って、ロックされた Python プロジェクトを実行します。Wireshark やキャプチャドライバーはインストールされません。

これらのプラグインマニフェストを含むチェックアウトから、使用するクライアントを選択してください。

# Codex
codex plugin marketplace add .
codex plugin add wireshark-mcp@wireshark-mcp

# Claude Code
claude plugin marketplace add .
claude plugin install wireshark-mcp@wireshark-mcp

ローカルインストール、旧バージョンの更新、環境設定、公開後の GitHub エントリポイントについては、プラグイン配布を参照してください。この方法か、以下の従来の登録方法のどちらか一方を選択してください。両方は使用しないでください。

従来の Python パッケージの利用方法

前提条件： Python 3.10 以降、および PATH 上に tshark がある Wireshark。

Wireshark MCP は、安定版の MCP Python SDK 2.x 系列（mcp>=2.1.1,<3）で動作します。

pip install wireshark-mcp
wireshark-mcp install   # choose from detected MCP clients

スクリプトや非対話型のターミナルでは、クライアントを明示的に選択してください。現在のプロジェクトにインストールする前に、プレビューを確認します。

wireshark-mcp install --client codex --scope project --dry-run
wireshark-mcp install --client codex --scope project

デフォルトのスコープは global です。--client を繰り返し指定するか、--client all を明示的に使用してください。設定を読み込むには、クライアントを再起動します。更新、削除、バックアップ、終了コードについては、インストールガイドを参照してください。

オプションの追加機能を導入すると、基本インストールに機能を追加できます。大容量キャプチャ用の DuckDB キャプチャインデックスを提供する index、GeoIP 拡張を提供する geoip、YARA スキャンを提供する yara、または all を指定できます。

pip install 'wireshark-mcp[index]'

コンテナーイメージとプラグインの利用方法には、追加機能は含まれていません。すべての設定、追加機能、制限については、設定リファレンスに記載されています。

このプロジェクトには、MCP と TShark CLI の完全な解析スキルも含まれています。スキルの検出と使用方法を参照してください。

問題がある場合は、wireshark-mcp doctor を実行してください。手動での設定やプラットフォーム固有の注意事項については、docs/manual-configuration.mdを参照してください。

---

クイックスタート

AI クライアントで .pcap ファイルを指定して、次を試してください。

Analyze capture.pcap using the Wireshark MCP tools.
Start with wireshark_open_file, then run wireshark_quick_analysis.
Use wireshark_aggregate for any capture-wide count or distribution.
Write findings to report.md.

大容量のキャプチャ、または関連する複数のキャプチャを扱う場合は、まずインデックスを作成し、ケースファイルで調査を進めてください。

Index big.pcapng with wireshark_index, then use wireshark_aggregate and
wireshark_index action="timeline" to find when 10.0.0.5 first appeared.
Open a case with wireshark_case, record every detector result you rely on,
and verify each conclusion with wireshark_get_packet_details.

---

ツール

実際の tshark 出力に基づく54個のツールを、カテゴリ別に整理しています。

カテゴリ	主な機能	数
エントリーとワークフロー	wireshark_open_file、wireshark_quick_analysis、wireshark_case（調査を継続して記録するケースファイル）	3
パケット解析	パケット一覧、詳細、バイト列、コンテキスト、ストリーム追跡、検索、ファイル情報	8
データ抽出	HTTP リクエスト、DNS クエリ、任意のフィールド、オブジェクトのエクスポート	4
統計	集計／グループ化／個別値／上位 k 件／時間バケット、プロトコル階層、エンドポイント、会話、I/O グラフ、エキスパート情報、サービス応答時間、フローグラフ	8
セキュリティと異常検知	認証情報スキャン、ポートスキャン、DNS トンネル、DoS、ビーコン通信、データ流出、プロトコル異常、YARA	8
プロトコル解析	wireshark_analyze_protocol（BLE ペアリング、スキャナー検出、ハンドルラベル付き GATT タイムライン、接続ライフサイクルを含む25のプロトコル）、TCP の健全性、ARP スプーフィング	3
復号と解析	TLS／WPA 復号、復号チェック、decode-as、プロトコル設定	5
フォレンジックと拡張情報	TLS フィンガープリント、ファイルシグネチャスキャン、GeoIP	3
ファイル操作、キャプチャ、ツール群	ライブキャプチャ、インターフェイス、マージ、フィルターを適用した保存、editcap によるトリミング／分割／重複排除／時刻シフト、フレーム抽出、text2pcap、機能	11
キャプチャインデックス（オプションの [index] 追加機能）	wireshark_index：tshark を1回実行してローカルの DuckDB ファイルを作成し、wireshark_aggregate と wireshark_extract_fields で再利用します。読み取り専用 SQL、複数キャプチャのセット、初回検出タイムライン、キャプチャ／ウィンドウの差分、Parquet エクスポート	1

1つのツールが25のプロトコルを扱います。1つのプロトコルにつき1つのツールを用意しているわけではありません。wireshark_analyze_protocol に protocol 引数（tls_handshakes、mqtt、modbus、s7comm、zigbee、wifi、rtp、kerberos、…）を渡すと、適切なフィールドと表示フィルターが適用されます。フィールド名が重要です。呼び出し側が s7comm.param.item.dbnum を推測する必要はありません。誤った推測をすると、クリーンなキャプチャのように見える空の結果が返されます。

サーバーの起動に必要なのは tshark だけです。オプションのツール（capinfos、mergecap、editcap、dumpcap、text2pcap）は自動検出され、利用可能な場合は追加機能が有効になります。

コンテキストコスト

ツール一覧はクライアントが送信するすべてのリクエストのプロンプトプレフィックスに含まれるため、そのサイズはリクエストごとに固定のコストとなります。デフォルトの構成は約 23 KB で、その内訳はパラメータスキーマが約 9 KB、説明が約 5 KB、読み取り／書き込みの注釈が約 3 KB です。また、再起動後もバイト単位で同一のため、クライアントはセッションごとに読み直す代わりにプレフィックスをキャッシュできます。

クライアントでライブトラフィックをキャプチャしたり、pcap を書き込んだりしない場合、--profile を使うと公開する内容を減らせます。

プロファイル	ツール	ペイロード	除外されるもの
full（デフォルト）	54	約 23 KB	なし
analysis	42	約 18 KB	ライブキャプチャ、インターフェース一覧表示、呼び出し元が指定するすべてのファイル書き込みツール
core	34	約 15 KB	上記に加え、復号、解析のオーバーライド、低レベルビュー

wireshark-mcp serve --profile core

実行時プロンプトとプロトコルの推奨事項は、選択したプロファイルに従います。静的ガイドでは full 専用のワークフローを説明している場合がありますが、サーバーはキャプチャ対象の検出中に、除外されたツールを推奨することはありません。

ツールの結果にも上限が設けられています。結果はセッション中、会話に残り続けるためです。8000 文字を超える出力は、先頭と末尾を残して途中を切り詰め、マーカーを付けます。残りの部分をページごとに取得するには、ツールの offset ／ limit ／ display_filter パラメータを使用します。上限は次の方法で引き上げたり引き下げたりできます。

export WIRESHARK_MCP_MAX_RESULT_CHARS=16000

各ツールには読み取り専用か書き込みを行うかも宣言されているため、クライアントは読み取り専用の解析ツール 41 個を自動承認し、ファイルを作成する 12 個（ライブキャプチャ、マージ、フィルター保存、editcap、text2pcap、フレーム抽出、オブジェクトエクスポート、ケースファイル）については引き続き承認を求めることができます。wireshark_index は非破壊としてマークされており、サーバー自身のインデックスキャッシュにのみ書き込みます。

3.0 以降、WIRESHARK_MCP_ALLOWED_DIRS に既存のディレクトリが指定されるまでは、これらのツールはフェイルクローズします。リモート HTTP/SSE バインドも、信頼できる認証済み TLS プロキシの背後で --allow-insecure-http を明示的に指定しない限り、ループバックのみで動作します。3.0 セキュリティ移行ガイドを参照してください。

---

ドキュメント

トピック	リンク
ドキュメントの一覧	docs/README.md
設定リファレンス（追加項目、環境変数、制限）	docs/configuration.md
キャプチャ全体の集計	docs/aggregation.md
キャプチャインデックス（DuckDB）	docs/capture-index.md
検出事項とケースファイル	docs/findings-and-cases.md
インストール、更新、アンインストール	docs/installation.md
プラットフォームのセットアップ（macOS/Linux/Windows）	docs/platform-validation.md
クライアントの手動設定	docs/manual-configuration.md
デプロイシナリオ	docs/deployment-scenarios.md
3.0 セキュリティ移行	docs/security-hardening-v3.md
プロンプトテンプレート	docs/prompt-engineering.md
アーキテクチャ	docs/architecture.md
リリースチェックリスト	docs/release-checklist.md
コントリビューション	CONTRIBUTING.md
変更履歴	CHANGELOG.md
機能ロードマップ	ROADMAP.md
セキュリティポリシー	SECURITY.md

---

開発

uv sync --group dev --extra index
uv run python -m pytest
uv run python -m ruff check src/ tests/

詳しいガイドについては、CONTRIBUTING.mdを参照してください。

---