mcpcap

mcpcap

PCAP ファイルを解析する、モジュール式の Python MCP（Model Context Protocol）サーバーです。mcpcap は、呼び出し時にローカルファイルのパスまたはリモートの HTTP URL を指定できる、プロトコル固有の解析ツールを提供します。そのため、サーバーはステートレスで、MCP クライアントとスムーズに連携できます。

概要

mcpcap はモジュール式のアーキテクチャを使用して、PCAP ファイルに含まれるさまざまなネットワークプロトコルを解析します。各モジュールには、それぞれ独立して任意の PCAP ファイルを指定して呼び出せる専用の解析ツールが用意されており、Claude Desktop やその他の MCP クライアントとの連携に最適です。

主な機能

• ステートレスな MCP ツール：各解析呼び出しで、個別の PCAP パスまたは URL を指定します
• モジュール式アーキテクチャ：DNS、DHCP、ICMP、TCP、SIP、CapInfos の各モジュールを備え、新しいプロトコルも簡単に追加できます
• 高度な TCP 解析：接続のライフサイクル、トラフィックパターン、再送信、フローの検査に対応します
• ローカルおよびリモートの PCAP に対応：ローカルストレージまたは HTTP URL のファイルを解析できます
• Scapy との連携：scapy の包括的なパケット解析機能を活用します
• 専門的な解析プロンプト：セキュリティ、ネットワーク、フォレンジックの解析ガイダンスを提供します
• JSON レスポンス：LLM での利用に最適化された構造化データ形式です

インストール

mcpcap の実行には Python 3.10 以降が必要です。

pip を使用する場合

pip install mcpcap

uv を使用する場合

uv add mcpcap

uvx を使用する場合（1 回限りの使用）

uvx mcpcap

Docker を使用する場合

リポジトリのルートからイメージをビルドします。

docker build -t mcpcap .

ネットワークエンドポイントに接続する MCP クライアント向けに、HTTP 経由で実行します。

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v "$(pwd)/examples:/pcaps:ro" \
  mcpcap --transport http --host 0.0.0.0 --port 8080 --allow-unauthenticated-http

docker run を直接起動できるクライアント向けに、stdio 経由で実行します。

docker run --rm -i \
  -v "$(pwd)/examples:/pcaps:ro" \
  mcpcap

ローカルのキャプチャファイルをコンテナにマウントする場合は、ツール呼び出しでコンテナ内のパスを使用します。

analyze_dns_packets("/pcaps/dns.pcap")

リモートの http:// および https:// PCAP URL は、呼び出し時に mcpcap がコンテナ内へダウンロードするため、ボリュームのマウントなしで使用できます。

Docker Compose を使用する場合

既定の HTTP ワークフローを使うには、同梱の Compose サービスを起動します。

docker compose up

このコマンドは ghcr.io/mcpcap/mcpcap:latest を取得し、ホストのループバックインターフェイス上でのみ http://127.0.0.1:8080/mcp を公開して、./examples を /pcaps としてコンテナにマウントします。

analyze_dns_packets("/pcaps/dns.pcap")

独自のキャプチャファイルを解析するには、docker-compose.yml のボリュームを ./examples:/pcaps:ro からローカルのキャプチャディレクトリに変更します。

GHCR のイメージではなく、チェックアウトしたソースを使ってローカルで開発する場合：

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

クイックスタート

1. MCP サーバーを起動する

mcpcap をステートレスな MCP サーバーとして起動します。

# Default stdio transport for Claude Desktop and similar clients
mcpcap

# Start with specific modules only
mcpcap --modules dns,tcp

# With packet analysis limits
mcpcap --max-packets 1000

# Start an HTTP transport server for remote MCP clients
mcpcap --transport http --host 127.0.0.1 --port 8080

2. MCP クライアントを接続する

Claude Desktop などのローカル MCP クライアントには、stdio トランスポートを使用します。

{
  "mcpServers": {
    "mcpcap": {
      "command": "mcpcap",
      "args": []
    }
  }
}

MCP クライアントがネットワークエンドポイントを必要とする場合は、HTTP トランスポートを使用します。

mcpcap --transport http --host 127.0.0.1 --port 8080

HTTP に対応した MCP クライアントの接続先を、次のように設定します。

http://127.0.0.1:8080/mcp

Docker を使用する場合は、次のように同じエンドポイントを公開できます。

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v "/path/to/captures:/pcaps:ro" \
  mcpcap --transport http --host 0.0.0.0 --port 8080 --allow-unauthenticated-http

または Compose を使用します。

docker compose up

ループバック以外のインターフェイスで HTTP をバインドするには、MCPCAP_AUTH_TOKEN 環境シークレットが必要です。シークレットマネージャーを使って強力なランダムシークレットを設定するか、シェル履歴に記録されない方法で入力してください。

read -rs -p "HTTP bearer token: " MCPCAP_AUTH_TOKEN
export MCPCAP_AUTH_TOKEN
mcpcap --transport http --host 0.0.0.0 --port 8080

クライアントはすべてのリクエストで Authorization: Bearer <secret> を送信する必要があります。リモートクライアントには、TLS リバースプロキシと HTTPS URL を使用してください。トークンを設定すると、ループバックエンドポイントも保護されます。stdio には影響しません。Docker の例では --allow-unauthenticated-http を使用してコンテナ内でバインドし、ホストのループバックインターフェイスでのみ公開します。このループバックのマッピングを維持し、信頼できるローカル Docker ネットワークを使用してください。同じネットワーク上の他のコンテナからはサービスに接続できます。Compose は MCPCAP_AUTH_TOKEN が設定されている場合にその値を転送するため、ローカルのコンテナエンドポイントも保護できます。詳しくはHTTP 統合ガイドを参照してください。

3. PCAP ファイルを分析する

分析ツールを呼び出す際にファイルパスまたは URL を指定すると、任意の PCAP ファイルを分析できます。

DNS 分析：

analyze_dns_packets("/path/to/dns.pcap")
analyze_dns_packets("https://example.com/remote.pcap")

DHCP 分析：

analyze_dhcp_packets("/path/to/dhcp.pcap")
analyze_dhcp_packets("https://example.com/dhcp-capture.pcap")

ICMP 分析：

analyze_icmp_packets("/path/to/icmp.pcap")
analyze_icmp_packets("https://example.com/ping-capture.pcap")

TCP 接続分析：

analyze_tcp_connections("/path/to/capture.pcap")
analyze_tcp_connections("/path/to/capture.pcap", server_ip="192.168.1.1", server_port=80)

TCP パターン分析：

analyze_tcp_anomalies("/path/to/capture.pcap", server_ip="10.0.0.1")

TCP 再送分析：

analyze_tcp_retransmissions("/path/to/capture.pcap")

トラフィックフロー分析：

analyze_traffic_flow("/path/to/capture.pcap", server_ip="192.168.1.100")

SIP 分析：

analyze_sip_packets("/path/to/voip-signaling.pcap")
analyze_sip_packets("https://example.com/sip-call-flow.pcap")

CapInfos 分析：

analyze_capinfos("/path/to/any.pcap")
analyze_capinfos("https://example.com/capture.pcap")

バインドマウントを使用して Docker を利用している場合は、ホスト側のパスではなくコンテナ内のパスを指定してください。

analyze_capinfos("/pcaps/dns.pcap")

利用可能なツール

DNS 分析ツール

• analyze_dns_packets(pcap_file)：DNS トラフィックを包括的に分析します
  • DNS クエリと応答を抽出します
  • クエリされたドメインとサブドメインを特定します
  • クエリの種類（A、AAAA、MX、CNAME など）を分析します
  • クエリの頻度とパターンを追跡します
  • 潜在的なセキュリティ上の問題を検出します

DHCP 分析ツール

• analyze_dhcp_packets(pcap_file)：DHCP トラフィックを包括的に分析します
  • DHCP トランザクション（DISCOVER、OFFER、REQUEST、ACK）を追跡します
  • DHCP クライアントとサーバーを特定します
  • IP アドレスの割り当てとリース情報を監視します
  • DHCP オプションと設定を分析します
  • DHCP の異常やセキュリティ上の問題を検出します

ICMP 分析ツール

• analyze_icmp_packets(pcap_file)：ICMP トラフィックを包括的に分析します
  • 応答時間とともに ping リクエストと応答を分析します
  • ネットワークの接続性と到達可能性に関する問題を特定します
  • TTL 値とルーティング経路（traceroute データ）を追跡します
  • ICMP エラーメッセージ（到達不能、時間超過）を検出します
  • ICMP ベースの攻撃や偵察の可能性を監視します

TCP 分析ツール

• analyze_tcp_connections(pcap_file, server_ip=None, server_port=None, detailed=False)：TCP 接続状態を分析します

  • TCP の 3 ウェイハンドシェイク（SYN、SYN-ACK、ACK）を追跡します
  • 接続のライフサイクルと終了（FIN、RST）を分析します
  • 成功した接続と失敗した接続を特定します
  • サーバー IP および／またはポートでフィルタリングします
  • 接続の問題や異常な切断を検出します

• analyze_tcp_anomalies(pcap_file, server_ip=None, server_port=None)：TCP トラフィックを観測・分析します

  • ハンドシェイク、フラグ、リセット、再送を要約します
  • 方向別の RST および再送パターンを明らかにします
  • 接続のライフサイクルに関する指標を報告します
  • さらなる調査に役立つ、事実に基づいたトラフィックパターンを返します

• analyze_tcp_retransmissions(pcap_file, server_ip=None, threshold=0.02)：TCP の再送を分析します

  • 全体および接続ごとの再送率を測定します
  • 品質に問題のある接続を特定します
  • 設定可能なしきい値と比較します
  • ネットワークの輻輳とパケット損失を検出します

• analyze_traffic_flow(pcap_file, server_ip, server_port=None)：双方向のトラフィックフローを分析します

  • クライアントからサーバーへのトラフィックと、サーバーからクライアントへのトラフィックを分析します
  • トラフィックの非対称性を特定します
  • RST パケットの送信元を判定します
  • 接続のパターンと挙動を解釈します

SIP 分析ツール

• analyze_sip_packets(pcap_file)：SIP シグナリングを分析します
  • UDP および TCP トランスポートを通じた SIP リクエストと応答を解析します
  • 通話識別子、CSeq 値、エンドポイント、主要なシグナリングヘッダーを抽出します
  • リクエストメソッドと応答コードのクラスを要約します
  • ユーザーエージェント、シグナリングサーバー、トランスポートの使用状況を明らかにします
  • VoIP のトラブルシューティング、セキュリティレビュー、フォレンジックな再構築をサポートします

CapInfos 分析ツール

• analyze_capinfos(pcap_file)：PCAP ファイルのメタデータと統計情報を分析します
  • ファイル情報（サイズ、名前、リンク層のカプセル化）
  • パケット統計（件数、データサイズ、平均パケットサイズ）
  • 時系列分析（期間、タイムスタンプ、パケットレート）
  • データスループットの指標（バイト／秒、ビット／秒）
  • Wireshark の capinfos(1) ユーティリティと同様です

分析プロンプト

mcpcap は、LLM による分析をガイドするための、用途に特化した分析プロンプトを提供します。

DNS プロンプト

• security_analysis - 脅威検出、DGA ドメイン、DNS トンネリングに焦点を当てます
• network_troubleshooting - DNS のパフォーマンスや設定の問題を特定します
• forensic_investigation - タイムラインの再構築と証拠の収集を行います

DHCP プロンプト

• dhcp_network_analysis - ネットワーク管理と IP 管理を行います
• dhcp_security_analysis - セキュリティ上の脅威と不正な DHCP の検出を行います
• dhcp_forensic_investigation - DHCP トランザクションのフォレンジック分析を行います

ICMP プロンプト

• icmp_network_diagnostics - ネットワーク接続と経路の分析を行います
• icmp_security_analysis - ICMP ベースの攻撃と偵察活動の検出を行います
• icmp_forensic_investigation - タイムラインの再構築とネットワークマッピングを行います

TCP プロンプト

• tcp_connection_troubleshooting - 接続の問題、ハンドシェイクの分析、切断パターンを扱います
• tcp_security_analysis - 攻撃の検出、ファイアウォールの分析、異常の特定を行います

SIP プロンプト

• sip_security_analysis - 登録の悪用、通話料金詐欺、シグナリングの露出を確認します
• sip_troubleshooting_analysis - 通話セットアップの進行、ルーティングの不一致、応答コードの失敗を扱います
• sip_forensic_investigation - Call-ID、CSeq、エンドポイント、トランスポートに基づいてタイムラインを再構築します

設定オプション

モジュールの選択

# Load specific modules
mcpcap --modules dns              # DNS analysis only
mcpcap --modules tcp              # TCP analysis only
mcpcap --modules dhcp             # DHCP analysis only
mcpcap --modules icmp             # ICMP analysis only
mcpcap --modules sip              # SIP analysis only
mcpcap --modules dns,tcp          # DNS and TCP analysis
mcpcap --modules dns,dhcp,icmp,tcp,sip,capinfos    # All modules (default)

分析の上限

# Limit packet analysis for large files
mcpcap --max-packets 1000

トランスポートオプション

# Default stdio transport
mcpcap

# HTTP transport for network-accessible MCP clients
mcpcap --transport http

# HTTP transport on a custom interface and port (requires MCPCAP_AUTH_TOKEN)
mcpcap --transport http --host 0.0.0.0 --port 9000

設定の完全な例

mcpcap --modules dns,dhcp,icmp,tcp,sip,capinfos --max-packets 500

CLI リファレンス

mcpcap [--modules MODULES] [--max-packets N] [--transport {stdio,http}] [--host HOST] [--port PORT] [--allow-unauthenticated-http]

オプション：

• --modules MODULES：読み込むモジュールをカンマ区切りで指定します（デフォルト：dns,dhcp,icmp,tcp,sip,capinfos）
  • 利用可能なモジュール：dns、dhcp、icmp、tcp、sip、capinfos
• --max-packets N：ファイルごとに分析するパケットの最大数を指定します（デフォルト：無制限）
• --transport {stdio,http}：公開する MCP トランスポートを指定します（デフォルト：stdio）
• --host HOST：HTTP トランスポートをバインドするホストを指定します（デフォルト：127.0.0.1）
• --port PORT：HTTP トランスポートをバインドするポートを指定します（デフォルト：8080）
• --allow-unauthenticated-http：Docker でループバックに公開したポートを使用する場合など、隔離されたローカル環境に限り、トークンなしでループバック以外のアドレスへのバインドを許可します

例：

# Start with all modules
mcpcap

# DNS and TCP analysis only
mcpcap --modules dns,tcp

# TCP analysis for troubleshooting connections
mcpcap --modules tcp

# With packet limits for large files
mcpcap --max-packets 1000

# Expose mcpcap over HTTP
mcpcap --transport http --host 127.0.0.1 --port 8080

例

PCAP ファイルの例は examples/ ディレクトリに含まれています。

• dns.pcap - DNS 分析のテスト用 DNS トラフィック
• dhcp.pcap - DHCP 4 ウェイハンドシェイクのキャプチャ

現在、examples/ に ICMP のサンプルキャプチャは含まれていません。

MCP Inspector での使用

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector mcpcap

次に、ツールをテストします。

// In the MCP Inspector web interface
analyze_dns_packets("./examples/dns.pcap")
analyze_dhcp_packets("./examples/dhcp.pcap")
analyze_capinfos("./examples/dns.pcap")
analyze_tcp_connections("/absolute/path/to/capture.pcap")
analyze_sip_packets("/absolute/path/to/voip-signaling.pcap")

アーキテクチャ

mcpcap のモジュール式設計により、簡単に拡張できます。

コアコンポーネント

1. BaseModule：ファイル処理、検証、リモートダウンロードを共有します
2. プロトコルモジュール：DNS、DHCP、ICMP、TCP、SIP、CapInfos の実装です
3. MCP インターフェース：ツールの登録とプロンプトの管理を行います
4. FastMCP フレームワーク：MCP サーバーを実装します

ツールのフロー

MCP Client Request → analyze_*_packets(pcap_file)
                  → BaseModule.analyze_packets()
                  → Module._analyze_protocol_file()
                  → Structured JSON Response

新しいモジュールの追加

次の手順で、新しいプロトコルモジュールを作成します。

1. BaseModule を継承します
2. _analyze_protocol_file(pcap_file) を実装します
3. MCP サーバーに分析ツールを登録します
4. 専用の分析プロンプトを追加します

今後、次のようなモジュールが追加される可能性があります。

• HTTP/HTTPS トラフィック分析
• UDP 接続分析
• BGP ルーティング分析
• SSL/TLS 証明書分析
• ネットワークフォレンジックツール
• ポートスキャン検出

リモートファイルのサポート

どちらの分析ツールも、HTTP/HTTPS URL を介してリモート PCAP ファイルを受け付けます。

# Examples of remote analysis
analyze_dns_packets("https://raw.githubusercontent.com/mcpcap/mcpcap/main/examples/dns.pcap")
analyze_dhcp_packets("https://example.com/network-capture.pcap")
analyze_icmp_packets("https://example.com/ping-test.pcap")
analyze_capinfos("https://example.com/network-metadata.pcap")
analyze_tcp_connections("https://example.com/tcp-session.pcap")
analyze_sip_packets("https://example.com/sip-signaling.pcap")

機能：

• 一時ファイルの自動ダウンロードと削除
• .pcap、.pcapng、.cap ファイルをサポート
• HTTP/HTTPS プロトコルをサポート

セキュリティに関する考慮事項

PCAP ファイルを分析する際は、次の点に注意してください。

• ファイルに機密性の高いネットワーク情報が含まれている場合があります
• リモートファイルは可能な場合、HTTPS 経由でダウンロードされます
• 一時ファイルは自動的に削除されます
• リモートファイルの出所と信頼性を確認してください

貢献

貢献を歓迎します！貢献できる分野は次のとおりです。

• 新しいプロトコルモジュール：HTTP、BGP、TLS、RTP などへの対応を追加します
• 分析の強化：既存の DNS／DHCP 分析を改善します
• セキュリティ機能：脅威検出機能をさらに追加します
• パフォーマンス：大容量の PCAP ファイル向けに分析を最適化します

ライセンス

MIT

要件

• Python 3.10+
• scapy（パケットの解析と分析）
• requests（リモートファイルへのアクセス）
• fastmcp（MCP サーバーのフレームワーク）

ドキュメント

• GitHub：github.com/mcpcap/mcpcap
• ドキュメント：docs.mcpcap.ai
• ウェブサイト：mcpcap.ai

サポート

質問、問題、機能リクエストがある場合は、GitHub で Issue を作成してください。