Show HN: Mcpsnoop – MCP(透過型プロキシとライブTUI)のためのWireshark
Show HN: Mcpsnoop – Wireshark for MCP (transparent proxy and live TUI) (github.com)
要約
Mcpsnoopは、AIクライアントとMCPサーバー間の実際のツール呼び出しをリアルタイムでターミナルに表示する透過型プロキシおよびデバッグツールです。従来のデバッガでは見えなかったクライアントとサーバー間の通信を可視化し、問題の特定を容易にします。JSON-RPCフレームのライブストリーム、リプレイ機能、設定不要のゼロコンフィグレーションなどが特徴です。
全文翻訳
CIにて
MCPのためのWireshark。 mcpsnoopは、AIクライアントとMCPサーバーの間に配置され、両者のJSON-RPCフレームを一切変更せずに記録します。ターミナルでライブ表示したり、検出内容に基づいてCIを失敗させたり、OpenTelemetryスパンとしてトレーシングバックエンドに送信したりできます。
[画像: CI] [画像: Go Reference] [画像: MIT] [画像: Marketplace]
問題点
公式のMCP Inspectorは、独自のクライアントとして接続するため、あなたのクライアント(Cursor, Claude Code, Codexなど)が実際にサーバーに送信しているものを決して見ることができません。また、リクエストが到着するのを待つタイプのツールは、モデルが呼び出されなかったコールや、間違った引数で呼び出されたコールを表示できません。ツールがサイレントに呼び出されなかったり、機能が一致しなかったり、コールがハングしたりすると、ログを掘り下げて推測するしかありません。
mcpsnoopは、実際のデータパスに配置されます。 サーバーコマンドをmcpsnoopでラップし、実際のクライアントとサーバーが通信する際のJSON-RPCフレームをライブで監視します。
このページはmcpsnoop GitHub Actionのリストでもありますので、そのすべてをここに記載します。キャプチャされたセッションをチェックし、検出されたすべての問題をコードスキャンアラートとしてファイルし、ゲートした内容に基づいてジョブを失敗させます。
permissions:
security-events: write
contents: read
steps:
- uses: kerlenton/mcpsnoop@v0.28.0
with:
session: artifacts/session.jsonl
キャプチャがない場合? 自分のクライアントで一度セッションを記録し、コミットして、アクションが各ビルドに対してそれをリプレイできるようにします。CIではモデルもAPIキーも実行されません。リプレイはキャプチャと同様にチェックされ、サーバーが記録時よりも悪化した場合はジョブも失敗します。Streamable HTTP経由でアクセスされるサーバーは、エンドポイントを持つtargetを取得し、記録はどちらのトランスポートでもリプレイされます。
steps:
- uses: kerlenton/mcpsnoop@v0.28.0
with:
replay: tests/mcp/claude-code-session.jsonl
server: node dist/index.js
好きなリリースをピン留めしてください。最新版はリリースページにあります。すべての入力と出力は、さらに下にあるThe GitHub Actionにあり、チェックが失敗する可能性のあるすべてのシグナルはdocs/CI.mdにあります。
OpenTelemetry
MCP revision 2026-07-28 は、プロトコルレベルのロギングを非推奨とし、実装に stderr を stdio 経由で、または構造化されたオブザーバビリティのために OpenTelemetry を使用するように指示しています。mcpsnoop は、クライアントやサーバーに触れることなく、両方に対応します。stdio サーバーの stderr 行は、フレームの横のストリームに表示され、各リクエストはMCPのOpenTelemetryセマンティック規約に従うスパンになります。
mcpsnoop export -T otlp -o trace.json # キャプチャからのスパン
mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js # コール完了時のスパン
ツールコールは tools/call search という名前のスパンとして到着し、mcp.method.name、gen_ai.tool.name、error.type を持ち、mcpsnoop のために構築されたダッシュボードではなく、MCP のために構築されたダッシュボードに配置されます。Prometheus 用のライブツールメトリクスは、フラグ1つで利用可能です。どちらもdocs/OPENTELEMETRY.mdにあります。
クイックスタート
セットアップなしで、すぐに試せます。
mcpsnoop demo
実際に使用するには、クライアントのMCP設定でサーバーをラップします。
{
"mcpServers": {
"my-server": {
"command": "mcpsnoop",
"args": ["--", "node", "build/index.js"]
}
}
}
-- より後のすべては、通常サーバーを起動するコマンドです。python server.py、npx -y @scope/server、またはコンパイル済みバイナリなど、すでに使用しているものに置き換えてください。
Claude Desktop では、その編集を手動で行う必要はありません。
mcpsnoop wrap my-server # my-server を mcpsnoop 経由でルーティング
mcpsnoop unwrap my-server # 元に戻す
wrap は claude_desktop_config.json を検索し、初回は claude_desktop_config.json.mcpsnoop.bak にコピーし、そのサーバーのエントリのみを書き換えるため、フォーマットや他のサーバーはそのまま残ります。書き換えられたエントリ内では、キーはアルファベット順に戻ります。unwrap はファイルを復元し、サーバーがラップされなくなるとバックアップを削除します。どちらかの操作の後、Claude Desktop を再起動してください。MCPサーバーは起動時に一度だけ起動されるためです。
その後、クライアントを通常通り使用し、UIを開きます。
mcpsnoop
フラグ、ソケットパス、起動順序を覚える必要はありません。シムとUIは自動的に互いを見つけ、UIはディスクから過去のセッションをバックフィルします。
Streamable-HTTPサーバーの場合、mcpsnoopをリバースプロキシとして実行します。
mcpsnoop http --target http://localhost:3000/mcp --listen :7000
各レスポンスのHTTPステータスはストリームに表示されるため、JSON-RPCメッセージ自体を持たないレスポンスも、何も表示されないのではなく、可視的なフレームとなります。これは、401チャレンジ、拒否されたオリジンに対する403、通知を認識する202、ターゲットに全く到達できなかった場合の502をカバーします。401のWWW-Authenticateヘッダーはそのままインスペクターに表示され、認証スキームと次のリソースメタデータを指定するため、そのまま保持されます。TUIで status:401 でフィルタリングするか、status:err で任意の障害をフィルタリングします。4xxまたは5xxはエラーと見なされるため、デフォルトのmcpsnoop check実行はそれに失敗し、応答したコールは待機中ではなく失敗として読み取られます。
自分のサーバーがない場合?実際に試すことで、公開されているテストサーバーに対して、自分のクライアントで操作できます。セッション発生後に検査するには、ログから過去のセッションを確認するを参照してください。
インストール
npm
Goツールチェーンは不要です。ほとんどのMCPサーバーはNodeまたはPythonで書かれているため、これが最も簡単な方法です。
npx mcpsnoop -- node build/index.js
npmパッケージは独自のコードを一切出荷しません。6つのプラットフォームパッケージそれぞれに1つのビルドが含まれており、npmはあなたのマシンに一致する単一のパッケージをインストールするため、インストール時にダウンロードするものはなく、プロキシでブロックされるものもありません。実行ごとに取得するのではなく、手元に置いておくには、npm i -g mcpsnoopを実行します。
Homebrew
brew install mcpsnoop
Go
go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest
すべてのプラットフォーム向けの事前ビルド済みバイナリはReleasesページにあります。
mcpsnoopはbash、zsh、fish、PowerShell用の補完機能を提供します。セットアップ手順については、mcpsnoop completion <shell> --helpを実行してください。これには、補完の有効化とOSごとのインストールパスが含まれます。
コマンド
| コマンド | 機能 |
|---|---|
mcpsnoop -- <server> | stdioサーバーを透過的なシムとしてラップする |
mcpsnoop | ライブTUIを開く |
mcpsnoop --metrics-listen <addr> | ヘッドレスハブを実行し、ライブPrometheusメトリクスを公開する |
mcpsnoop http --target <url> | Streamable-HTTPサーバーをプロキシする |
mcpsnoop export | セッションをjson、html、text、har、またはotlpにレンダリングする |
mcpsnoop check | エラー、無効なフレーム、ツールの結果が自身のoutputSchemaを壊すような警告、ルーティングの不一致、ハングしたコール、遅延した結果、複数回実行された可能性のあるコール、ツールのドリフト、緩んだり意味のないアノテーション、またはレイテンシ予算に基づいてCIを失敗させる |
mcpsnoop baseline | 信頼されたツールの定義を検査、承認、またはリセットする |
mcpsnoop diff | 2つのキャプチャされたセッション間でツールとコールを比較する |
mcpsnoop open | 保存されたセッションをTUIで開く |
mcpsnoop mock <session> | キャプチャされたセッションをstdio MCPサーバーとして提供する |
mcpsnoop replay <session> -- <server> | stdioまたはStreamable HTTP経由でサーバーを駆動し、記録されたセッションのクライアント側を使用し、結果を記録と比較する |
mcpsnoop inventory | このマシンでmcpsnoopを実行したすべてのサーバーをリストする |
mcpsnoop stats | 保存されたすべてのキャプチャをサーバーとツールごとに1行に折りたたむ |
mcpsnoop clients | 各MCPクライアントが実際にワイヤ上で何を行ったかを、名前とバージョンで表示する |
mcpsnoop prune | 指定されたカットオフより古い保存されたセッションログを削除する |
mcpsnoop wrap <server> | Claude Desktopのサーバーの1つをmcpsnoop経由でルーティングする |
mcpsnoop unwrap <server> | そのサーバーのエントリを元に戻す |
mcpsnoop remote <user@host> | SSHトンネルコマンドを出力する |
mcpsnoop demo | スクリプト化されたセッションを再生する |
完全なリストについては mcpsnoop help を実行するか、特定のコマンドのフラグについては mcpsnoop help <command> を実行してください。
比較
これらの各ツールは異なる質問に答えます。ツールの配置場所によって、どの質問に答えられるかが決まります。
| ツール | 配置場所 | 用途 |
|---|---|---|
| MCP Inspector | 独自のクライアント、サーバーに接続 | サーバーを手動で試す、ブラウザまたはスクリプト可能なCLIから |
| Snyk Agent Scan | 独自のクライアント、設定内のサーバーを起動または接続してツールを読み取る | マシン上のエージェント、MCPサーバー、スキルをプロンプトインジェクションや脆弱性に対してスキャンする |
| MCP Observatory | 独自のクライアント、サーバーをテスト、記録、検証するために起動する | CIでのセキュリティおよびリグレッションテスト、攻撃シミュレーション、スキーマドリフト、記録、リプレイ、検証を含む |
| mcprec | ワイヤ上、クライアントとサーバーの間 | セッションを一度記録し、ネットワークなしでテストフィクスチャとしてリプレイする |
| mcpsnoop | ワイヤ上、クライアントとサーバーの間 | 実際のクライアントとサーバーの通信を監視する、各ビルドに対して実際のクライアントのセッションをリプレイする、それに基づいてCIを失敗させる、OpenTelemetryとしてエクスポートする |
独自のクライアントであるツールは、自身が行ったコールを見ることはできますが、あなたのクライアントが行ったコールを見ることはできないため、モデルが呼び出さなかったコールや間違った引数で呼び出したコールを表示できません。スキャナーは、信頼する前に定義を読み取ります。mcpsnoopは、信頼した後に何が起こるかを監視します。これには、定義が後で変更されるかどうかまで含まれます。
仕組み
[画像: mcpsnoopはAIクライアントとMCPサーバー間のパイプに配置され、すべてのJSON-RPCフレームをライブターミナルUIにコピーします]
mcpsnoopは、1つのバイナリに2つの役割があります。mcpsnoop -- <server>は、クライアントが起動する透過的なシムであり、バイトをそのまま転送しながら、各フレームのコピーをハブに送信します。引数なしのmcpsnoopはそのハブとそのライブTUIです。これらは、よく知られたソケットとディスク上のログを通じてペアになるため、どちらかが先に開始する必要はありません。
サイドにあるInspectorのようにオフサイドにあるのではなく、実際のパイプに配置されるため、実際のクライアントとサーバーが互いに何を言っているのかを正確に把握できます。サーバーが何で書かれていても関係ありません。メモリとディスクの制限はdocs/HOW_IT_WORKS.mdに記載されています。
GitHub Action
以下は、アクションがあなたのために行うすべてです。mcpsnoopをインストールし、キャプチャをチェックし、検出された問題をセキュリティタブにファイルし、あなたがゲートした内容に基づいてジョブを失敗させます。
permissions:
security-events: write
contents: read
steps:
- uses: kerlenton/mcpsnoop@v0.28.0
with:
session: artifacts/session.jsonl
好きなリリースをピン留めしてください。最新版はリリースページにあります。意図的にv1のような浮動バージョンはありません。ピン留めされたリリースは、アクションがインストールするバイナリでもあるため、両者が一致しないことはなく、古くなるバージョンデフォルトもありません。
| 入力 | |
|---|---|
session | チェックする.jsonlキャプチャ、またはそれらのディレクトリ。リポジトリのルートからの相対パス。これを指定するか、replayを指定します |
replay | serverまたはtargetに対してリプレイするコミットされた記録。その後、キャプチャがチェックされ、リグレッションが発生した場合にジョブが失敗します |
server | テスト対象のサーバーを起動するコマンド。コマンドラインで指定する形式で引用符で囲みます。replayとstdioサーバーの場合に必要です。targetと一緒の場合、まずHTTPサーバーを起動し、すでに実行中の場合は省略できます |
target | リプレイ対象のStreamable HTTPエンドポイント。例: http://localhost:3000/mcp。認証情報はreplay-argsに--headerとして指定し、ステップログに非表示で表示されます |
replay-args | その他のreplayフラグ。例: --read-only。--outは拒否されます。アクションがキャプチャの保存場所を決定するため |
fail-on | --fail-onと同様。CLIのデフォルト値がデフォルトです |
args | その他のcheckフラグ。コマンドラインで指定する形式で引用符で囲みます。--formatは拒否されます。アクションがレポートを読み取るため |
upload-sarif | レポートをコードスキャンに送信します。true |
category | コードスキャンの名前空間。mcpsnoop。マトリックスの各レッグで変更するか、レッグが上書きされます |
fail-on-findings | 検出された問題でジョブを失敗させます。true。アラートをファイルし、コードスキャンの必須チェックに決定させるにはfalseに設定します |
version | インストールするmcpsnoopのバージョン。ピン留めされたリリースがデフォルトです |
install | mcpsnoopが既にPATH上にある場合false。これは、リリースがビルドされていないプラットフォームでのアクセス方法です |
出力は outcome、sarif、exit-code、capture(チェックされたキャプチャのパス)です。replayの場合、これはリプレイが書き込んだもので、アーティファクトとして保持する価値があります。outcomeはpassed、findings、またはerrorです。errorは別途処理する価値があります。これは何もチェックされなかったことを意味し、何も検出されなかったこととは異なります。チェックできなかった実行は、fail-on-findingsの設定に関わらずジョブを失敗させます。 なぜなら、何も検証せずにグリーンになったパイプラインは、何も検出されなかったことよりも悪いからです。
ジョブには security-events: write が必要です。それがない場合、アップロードは403エラーになります。コードスキャンがないリポジトリでは upload-sarif: false を設定してください。アクションなしで同じチェックを実行した場合、失敗する可能性のあるシグナルと終了コードはdocs/CI.mdに記載されています。
ドキュメント
| ページ | 内容 |
|---|---|
| CIでのセッションチェック | 各ビルドに対する記録のリプレイ、checkが失敗する可能性のあるすべてのシグナル、終了コード、アサーション、JUnitおよびSARIFレポート、2つのセッションの比較、アクションなしでの配線 |
| OpenTelemetryとPrometheus | スパンとその内容、コレクターへのストリーミング、ライブツールメトリクス |
| mcpsnoopの使用 | キー、フィルタリング、エクスポートフォーマット、リプレイ、サーバーがユーザーに要求したもの、コンテキストでのコスト、キャプチャ全体の統計、各クライアントが実際に送信したもの、サーバーインベントリ、リモートマシン、設定ファイル |
| 機密情報のマスキング | キャプチャ中または既存のキャプチャからのシークレットのスクラブ |
| 仕組み | メモリ制限、履歴制限、古いログの削除 |
| 実際に試す | 公開されているテストサーバー、自分のクライアントで駆動 |
| 過去のセッションのレビュー | セッションログの保存場所と、後で開く方法 |
| キャプチャフォーマット | セッションログの各行の内容と、それが決して変更されないこと、キャプチャを読み取るツールのためのJSONスキーマ |
セキュリティ
mcpsnoopはあなたがラップするサーバーコマンドを実行するため、信頼できるサーバーのみをラップし、信頼できないものはコンテナで実行してください。クライアント設定に含めたもの以外は何も実行しません。
リモートワークフローの場合、SSHトンネリングまたはSSHファイル転送を使用して、トランスポート認証、暗号化、ホスト検証、キーローテーション、監査ポリシーを既存のSSHセットアップに維持してください。
キャプチャがターミナルに与える影響
キャプチャは、相手側が選択したデータです。フレームとstderr行にはターミナルエスケープシーケンスが含まれる可能性があり、ターミナルは表示の乱れからシステムクリップボードへの書き込み(OSC 52)まで、渡されたものすべてに対してアクションを実行します。mcpsnoopは、自身が生成した色シーケンスのみを保持し、フレームがターミナルに到達する前に他のすべてのエスケープをドロップします。テーブルセルは制御文字を引用符で囲んで表示し、インスペクターはそれらをフルスペルで表示し、クリップボードコピーはエスケープされた形式で持ち運ぶため、何も隠されることなく、何も実行されません。
キャプチャの内容
キャプチャされたフレームには、プロンプト、ツール引数、認証情報、ツールの結果が含まれる場合があります。docs/REDACTION.mdでは、キャプチャ中またはキャプチャ後にそれらをスクラブする方法について説明しています。脆弱性を報告するには、SECURITY.mdを参照してください。
貢献
イシューとプルリクエストを歓迎します。詳細はCONTRIBUTING.mdを参照してください。