kerlenton/mcpsnoopWireshark für MCP. Ein transparenter Proxy zwischen deinem KI-Client und dem MCP-Server. Beobachte jeden Aufruf live in deinem Terminal, lass CI bei Funden fehlschlagen, exportiere OpenTelemetry-Spans.
<p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/9109/91d664ea266713affb29238906792777021b43fa6627b13f46382f48ad340a61.png" alt="mcpsnoop" width="440"> </p> **Wireshark für MCP.** mcpsnoop sitzt zwischen deinem KI-Client und deinem MCP-Server und zeichnet jeden JSON-RPC-Frame auf, den beide austauschen, ohne dass eine der beiden Seiten geändert werden muss. Beobachte es live in deinem Terminal, lass CI aufgrund der Befunde fehlschlagen oder sende es als OpenTelemetry-Spans an dein Tracing-Backend. [](https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/kerlenton/mcpsnoop) [](LICENSE) [](https://github.com/marketplace/actions/mcpsnoop) <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/9109/30466d77be15250e4bab6639e48a4cd5b0d44cd96e48606b60c6bacb67c15c3d.gif" alt="mcpsnoop demo"> </p> ## Das Problem Der offizielle [MCP Inspector](https://github.com/modelcontextprotocol/inspector) verbindet sich als eigener Client und sieht daher nie, was *dein* Client (Cursor, Claude Code, Codex) tatsächlich an deinen Server sendet. Und alles, was auf das Eintreffen einer Anfrage wartet, kann den Aufruf nicht zeigen, den das Modell nie ausgeführt hat oder mit den falschen Argumenten ausgeführt hat. Wenn ein Tool stillschweigend nicht aufgerufen wird, die Capabilities nicht zusammenpassen oder ein Aufruf einfach hängt, bleibt dir nur das Durchwühlen von Logs und Raten. **mcpsnoop sitzt stattdessen im echten Datenpfad.** Umgib deinen Server-Befehl damit und beobachte jeden JSON-RPC-Frame live, während dein echter Client und Server kommunizieren. ## In CI Diese Seite ist auch der Eintrag für die [mcpsnoop GitHub Action](https://github.com/marketplace/actions/mcpsnoop), hier also der vollständige Inhalt. Sie prüft eine aufgezeichnete Sitzung, meldet jeden Befund als Code-Scanning-Alert und lässt den Job anhand dessen fehlschlagen, worauf du die Prüfung beschränkt hast. ```yaml permissions: security-events: write contents: read steps: - uses: kerlenton/[email protected] with: session: artifacts/session.jsonl ``` Keine Aufzeichnung zur Hand? Zeichnen Sie einmal eine Sitzung mit Ihrem eigenen Client auf, committen Sie sie und lassen Sie die Action sie gegen jeden Build erneut abspielen. In CI läuft weder ein Modell noch ein API-Schlüssel. Die Wiedergabe wird wie jede Aufzeichnung geprüft, und der Job schlägt auch fehl, wenn der Server schlechter geworden ist als in der Aufzeichnung. Ein Server, der über Streamable HTTP erreicht wird, erhält `target` mit seinem Endpoint, und eine Aufzeichnung lässt sich über beide Transportwege wiedergeben. ```yaml steps: - uses: kerlenton/[email protected] with: replay: tests/mcp/claude-code-session.jsonl server: node dist/index.js ``` Binden Sie die gewünschte Version ein. Die neueste finden Sie auf der [Releases-Seite](https://github.com/kerlenton/mcpsnoop/releases). Jede Eingabe und Ausgabe ist weiter unten in [The GitHub Action](#the-github-action) aufgeführt, und jedes Signal, bei dem die Prüfung fehlschlagen kann, ist in [docs/CI.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md) dokumentiert. ## OpenTelemetry MCP-Revision 2026-07-28 stuft Logging auf Protokollebene als veraltet ein und weist Implementierungen an, auf `stderr` bei stdio oder auf OpenTelemetry für strukturierte Observability umzusteigen. mcpsnoop deckt beides ab, ohne den Client oder den Server zu verändern. Die `stderr`-Zeilen eines stdio-Servers erscheinen im Stream neben seinen Frames, und jede Anfrage wird zu einem Span, der den [OpenTelemetry-Semantikkonventionen für MCP](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/model/mcp) folgt. ```bash mcpsnoop export -T otlp -o trace.json # spans from a capture mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js # spans as calls complete ``` Ein Tool-Aufruf kommt als Span namens `tools/call search` an und trägt `mcp.method.name`, `gen_ai.tool.name` und `error.type`, sodass er in einem für MCP gebauten Dashboard landet statt in einem für mcpsnoop gebauten. Live-Tool-Metriken für Prometheus sind nur einen Flag entfernt. Beides ist in [docs/OPENTELEMETRY.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/OPENTELEMETRY.md) beschrieben. ## Schnellstart Sofort ansehen, ohne etwas einrichten zu müssen. ```bash mcpsnoop demo ``` Um es tatsächlich zu nutzen, binden Sie Ihren Server in die MCP-Konfiguration Ihres Clients ein. ```json { "mcpServers": { "my-server": { "command": "mcpsnoop", "args": ["--", "node", "build/index.js"] } } } ``` Alles nach `--` ist der Befehl, der normalerweise deinen Server startet. Ersetze ihn durch das, was du bereits verwendest, etwa `python server.py`, `npx -y @scope/server` oder eine kompilierte Binärdatei. Auf Claude Desktop musst du diese Änderung nicht von Hand vornehmen. ```bash mcpsnoop wrap my-server # route my-server through mcpsnoop mcpsnoop unwrap my-server # put it back ``` `wrap` findet `claude_desktop_config.json`, kopiert die Datei beim ersten Mal nach `claude_desktop_config.json.mcpsnoop.bak` und schreibt nur den Eintrag dieses einen Servers um, sodass deine Formatierung und alle anderen Server unangetastet bleiben. Innerhalb des umgeschriebenen Eintrags werden die Schlüssel in alphabetischer Reihenfolge zurückgegeben. `unwrap` stellt die Datei wieder her und entfernt die Sicherung, sobald kein Server mehr umschlossen ist. Starte Claude Desktop nach beidem neu, da MCP-Server beim Start einmalig gestartet werden. Verwende dann deinen Client wie gewohnt und öffne die UI. ```bash mcpsnoop ``` Keine Flags, keine Socket-Pfade, keine Startreihenfolge, an die man sich erinnern muss. Das Shim und die UI finden sich von selbst, und die UI füllt vergangene Sitzungen von der Festplatte nach. Für einen streamable-HTTP-Server führen Sie mcpsnoop als Reverse-Proxy aus. ```bash mcpsnoop http --target http://localhost:3000/mcp --listen :7000 ``` Der HTTP-Status jeder Antwort erscheint im Stream, sodass eine Antwort, die keine eigene JSON-RPC-Nachricht enthält, dennoch als sichtbarer Frame erscheint und nicht als nichts. Das umfasst die 401-Herausforderung, die 403 bei einem abgelehnten Origin, die 202, die eine Benachrichtigung bestätigt, und die 502, wenn das Ziel überhaupt nicht erreichbar ist. Der `WWW-Authenticate`-Header einer 401 wird unverändert beibehalten und im Inspector angezeigt, da er das Authentifizierungsschema und die Ressourcen-Metadaten benennt, zu denen als Nächstes gegangen werden soll. Filtere nach Status mit `status:401` in der TUI oder nach jedem Fehler mit `status:err`. Ein 4xx oder 5xx zählt als Fehler, sodass ein standardmäßiger `mcpsnoop check`-Lauf daran scheitert, und der beantwortete Aufruf gilt als fehlgeschlagen und nicht als noch wartend. Kein eigener Server? [Probiere es live aus](https://github.com/kerlenton/mcpsnoop/blob/main/docs/TRY_IT.md) gegen einen veröffentlichten Testserver, gesteuert von deinem eigenen Client. Um eine Sitzung im Nachhinein zu inspizieren, siehe [vergangene Sitzungen aus Logs überprüfen](https://github.com/kerlenton/mcpsnoop/blob/main/docs/POST_MORTEM.md). ## Installation ### npm Keine Go-Toolchain erforderlich. Die meisten MCP-Server sind in Node oder Python geschrieben, daher ist dies der kürzeste Weg. ```bash npx mcpsnoop -- node build/index.js ``` Das npm-Paket enthält keinen eigenen Code. Sechs Plattform-Pakete enthalten jeweils einen Build, und npm installiert nur das eine, das zu deiner Maschine passt, sodass zur Installationszeit nichts heruntergeladen werden muss und nichts in einem Proxy freigegeben werden muss. Um es dauerhaft zu behalten, statt es bei jedem Lauf erneut abzurufen, `npm i -g mcpsnoop`. ### Homebrew ```bash brew install mcpsnoop ``` ### Go ```bash go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest ``` Vorkompilierte Binärdateien für jede Plattform finden sich auf der [Releases](https://github.com/kerlenton/mcpsnoop/releases)-Seite. mcpsnoop liefert Vervollständigungen für bash, zsh, fish und PowerShell. Führe `mcpsnoop completion <shell> --help` aus, um die Einrichtungsschritte zu sehen, die das Aktivieren der Vervollständigung und den Installationspfad für dein Betriebssystem abdecken. ## Befehle | Befehl | Was er tut | |---|---| | `mcpsnoop -- <server>` | einen stdio-Server als transparenten Shim umhüllen | | `mcpsnoop` | die Live-TUI öffnen | | `mcpsnoop --metrics-listen <addr>` | einen Headless-Hub ausführen und Live-Prometheus-Metriken bereitstellen | | `mcpsnoop http --target <url>` | einen Streamable-HTTP-Server als Proxy weiterleiten | | `mcpsnoop export` | eine Sitzung als json, html, text, har oder otlp rendern | | `mcpsnoop check` | CI bei Fehlern fehlschlagen lassen, bei ungültigen Frames, bei Warnungen wie einem Tool-Ergebnis, das sein eigenes outputSchema verletzt, bei Routing-Abweichungen, hängenden Aufrufen, verspäteten Ergebnissen, Aufrufen, die möglicherweise zweimal ausgeführt wurden, bei Tool-Drift, bei Annotations, die gelockert wurden oder nichts aussagen, oder bei einem Latenz-Budget | | `mcpsnoop baseline` | vertrauenswürdige Tool-Definitionen inspizieren, akzeptieren oder zurücksetzen | | `mcpsnoop diff` | Tools und Aufrufe über zwei aufgezeichnete Sitzungen hinweg vergleichen | | `mcpsnoop open` | eine gespeicherte Sitzung in der TUI öffnen | | `mcpsnoop mock <session>` | eine aufgezeichnete Sitzung als stdio-MCP-Server wieder bereitstellen | | `mcpsnoop replay <session> -- <server>` | einen Server über stdio oder Streamable HTTP mit der Client-Seite einer aufgezeichneten Sitzung ansteuern und das Ergebnis mit der Aufzeichnung vergleichen | | `mcpsnoop inventory` | jeden Server auflisten, der auf dieser Maschine durch mcpsnoop gelaufen ist | | `mcpsnoop stats` | jede gespeicherte Aufzeichnung zu einer Zeile pro Server und Tool zusammenfassen | | `mcpsnoop clients` | anzeigen, was jeder MCP-Client tatsächlich auf der Leitung getan hat, nach Name und Version | | `mcpsnoop prune` | gespeicherte Sitzungsprotokolle löschen, die älter als ein Stichtag sind | | `mcpsnoop wrap <server>` | einen der Server von Claude Desktop durch mcpsnoop leiten | | `mcpsnoop unwrap <server>` | den Eintrag dieses Servers wieder in den ursprünglichen Zustand versetzen | | `mcpsnoop remote <user@host>` | den SSH-Tunnel-Befehl ausgeben | | `mcpsnoop demo` | eine geskriptete Sitzung abspielen | Führe `mcpsnoop help` für die vollständige Liste aus, oder `mcpsnoop help <command>` für die Flags eines einzelnen Befehls. ## Wie es sich vergleicht Jedes dieser Werkzeuge beantwortet eine andere Frage, und wo ein Werkzeug sitzt, entscheidet darüber, welche Fragen es beantworten kann. | Werkzeug | Wo es sitzt | Wofür es gedacht ist | |---|---|---| | [MCP Inspector](https://github.com/modelcontextprotocol/inspector) | eigener Client, verbunden mit deinem Server | einen Server von Hand ausprobieren, im Browser oder über eine skriptbare CLI | | [Snyk Agent Scan](https://github.com/snyk/agent-scan) | eigener Client, startet oder verbindet sich mit den Servern in deinen Konfigurationen, um deren Tools zu lesen | Agents, MCP-Server und Skills auf deiner Maschine auf Prompt-Injection und Schwachstellen scannen | | [MCP Observatory](https://github.com/KryptosAI/mcp-observatory) | eigener Client, startet deinen Server, um ihn zu testen, aufzuzeichnen und zu verifizieren | Sicherheits- und Regressionstests in CI, mit Angriffssimulation, Schema-Drift sowie Aufzeichnen, Wiedergeben und Verifizieren | | [mcprec](https://github.com/erphq/mcprec) | auf der Leitung, zwischen Client und Server | eine Sitzung einmal aufzeichnen und ohne Netzwerk als Test-Fixture wiedergeben | | mcpsnoop | auf der Leitung, zwischen Client und Server | beobachten, was dein echter Client und Server sagen, die Sitzung eines echten Clients gegen jeden Build wiedergeben, CI daran scheitern lassen und als OpenTelemetry exportieren | Ein Werkzeug, das sein eigener Client ist, sieht die Aufrufe, die es selbst macht, nicht die, die dein Client macht, daher kann es den Aufruf nicht zeigen, den dein Modell nie gemacht hat oder mit den falschen Argumenten gemacht hat. Ein Scanner liest eine Definition, bevor du ihr vertraust. mcpsnoop beobachtet, was passiert, nachdem du es getan hast, einschließlich ob sich die Definition später ändert. ## Wie es funktioniert <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg"> <img alt="mcpsnoop sitzt in der Leitung zwischen deinem KI-Client und deinen MCP-Servern und kopiert jeden JSON-RPC-Frame in eine Live-Terminal-UI" src="https://raw.githubusercontent.com/kerlenton/mcpsnoop/HEAD/assets/architecture-light.svg" width="760"> </picture> </p> mcpsnoop vereint zwei Rollen in einer einzigen Binärdatei. `mcpsnoop -- <server>` ist der transparente Shim, den dein Client startet; er leitet Bytes unverändert weiter und schickt gleichzeitig eine Kopie jedes Frames an den Hub. `mcpsnoop` ohne Argumente ist dieser Hub und seine Live-TUI. Sie koppeln sich über einen bekannten Socket und Logs auf der Festplatte, sodass keiner von beiden zuerst gestartet werden muss. Weil es in der tatsächlichen Pipe sitzt und nicht daneben wie der Inspector, sieht es genau, was dein echter Client und Server zueinander sagen, egal in welcher Sprache der Server geschrieben ist. Was seinen Speicher und seine Festplatte begrenzt, steht in [docs/HOW_IT_WORKS.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/HOW_IT_WORKS.md). ## Die GitHub Action Alles Folgende ist das, was die Action für dich erledigt. Sie installiert mcpsnoop, prüft die Aufzeichnung, legt die Befunde im Security-Tab ab und lässt den Job an dem scheitern, worauf du die Prüfung beschränkt hast. ```yaml permissions: security-events: write contents: read steps: - uses: kerlenton/[email protected] with: session: artifacts/session.jsonl ``` Pinnen Sie ein Release, welches Sie möchten. Das neueste finden Sie auf der [Releases-Seite](https://github.com/kerlenton/mcpsnoop/releases). Es gibt bewusst kein gleitendes `v1`. Das gepinnte Release ist auch die Binärdatei, die die Action installiert, sodass die beiden nie voneinander abweichen können und es keinen Versionsstandard gibt, der veralten könnte. | Eingabe | | |---|---| | `session` | die zu prüfende `.jsonl`-Aufzeichnung oder ein Verzeichnis davon, relativ zum Repository-Stamm. Geben Sie dies oder `replay` an | | `replay` | eine committete Aufzeichnung, die gegen `server` oder `target` abgespielt wird, deren Aufzeichnung dann geprüft wird und die den Job bei einer Regression ebenfalls fehlschlagen lässt | | `server` | der Befehl, der den zu testenden Server startet, in Anführungszeichen wie auf einer Kommandozeile. Erforderlich mit `replay` für einen stdio-Server. Mit `target` startet er zuerst einen HTTP-Server und kann weggelassen werden, wenn bereits einer läuft | | `target` | der Streamable-HTTP-Endpunkt, gegen den abgespielt wird, etwa `http://localhost:3000/mcp`. Ein Zugangsdatenwert gehört als `--header` in `replay-args`, und das Schrittprotokoll zeigt seinen Wert verborgen an | | `replay-args` | alle weiteren `replay`-Flags, etwa `--read-only`. `--out` wird abgelehnt, da die Action entscheidet, wohin die Aufzeichnung geht | | `fail-on` | wie `--fail-on`, standardmäßig der Standardwert der CLI | | `args` | alle weiteren `check`-Flags, in Anführungszeichen wie auf einer Kommandozeile. `--format` wird abgelehnt, da die Action den Bericht liest | | `upload-sarif` | den Bericht an das Code Scanning senden. `true` | | `category` | der Namespace für das Code Scanning. `mcpsnoop`. Variieren Sie ihn pro Lauf einer Matrix, sonst überschreiben sich die Läufe gegenseitig | | `fail-on-findings` | den Job bei einem Befund fehlschlagen lassen. `true`. Auf `false` setzen, um die Warnungen zu melden und den erforderlichen Check des Code Scannings entscheiden zu lassen | | `version` | welches mcpsnoop installiert werden soll. Standardmäßig das Release, das Sie gepinnt haben | | `install` | `false`, wenn mcpsnoop bereits im PATH liegt, was der Weg auf einer Plattform ist, für die kein Release gebaut wird | Ausgaben sind `outcome`, `sarif`, `exit-code` und `capture`, der Pfad der geprüften Aufzeichnung, die bei `replay` die vom Replay geschriebene ist und es wert ist, als Artefakt aufbewahrt zu werden. `outcome` ist `passed`, `findings` oder `error`, und der dritte Fall ist es wert, gesondert behandelt zu werden. Er bedeutet, dass nichts geprüft wurde, was nicht dasselbe ist wie nichts gefunden zu haben. **Ein Lauf, der nicht prüfen konnte, lässt den Job fehlschlagen, unabhängig davon, was `fail-on-findings` sagt**, denn eine Pipeline, die grün wird, ohne etwas verifiziert zu haben, ist schlimmer als eine, die fehlschlägt. Der Job benötigt `security-events: write`, sonst antwortet der Upload mit 403. Setzen Sie `upload-sarif: false` in einem Repository ohne Code Scanning. Wie Sie dieselbe Prüfung ohne die Action ausführen, welche Signale sie fehlschlagen lassen können und die Exit-Codes finden Sie in [docs/CI.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md). ## Dokumentation | Seite | Was darin steht | |---|---| | [Sitzungen in CI prüfen](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md) | eine Aufzeichnung gegen jeden Build abspielen, jedes Signal, bei dem `check` fehlschlagen kann, Exit-Codes, Assertions, JUnit- und SARIF-Berichte, zwei Sitzungen vergleichen und die Einrichtung ohne die Action | | [OpenTelemetry und Prometheus](https://github.com/kerlenton/mcpsnoop/blob/main/docs/OPENTELEMETRY.md) | die Spans und was sie tragen, das Streamen an einen Collector und Live-Tool-Metriken | | [mcpsnoop verwenden](https://github.com/kerlenton/mcpsnoop/blob/main/docs/USING.md) | Tasten, Filtern, Exportformate, Replay, was ein Server von Ihrem Benutzer angefordert hat, Kosten im Kontext, Statistiken über Aufzeichnungen hinweg, was jeder Client tatsächlich sendet, das Server-Inventar, entfernte Maschinen und die Konfigurationsdatei | | [Redaction](https://github.com/kerlenton/mcpsnoop/blob/main/docs/REDACTION.md) | Geheimnisse bereinigen, während der Aufzeichnung oder aus einer bereits vorhandenen Aufzeichnung | | [Wie es funktioniert](https://github.com/kerlenton/mcpsnoop/blob/main/docs/HOW_IT_WORKS.md) | Speichergrenzen, das Verlaufslimit und das Bereinigen alter Logs | | [Echt ausprobieren](https://github.com/kerlenton/mcpsnoop/blob/main/docs/TRY_IT.md) | ein veröffentlichter Testserver, angetrieben von Ihrem eigenen Client | | [Vergangene Sitzungen überprüfen](https://github.com/kerlenton/mcpsnoop/blob/main/docs/POST_MORTEM.md) | wo Sitzungslogs liegen und wie man eine im Nachhinein öffnet | | [Das Aufzeichnungsformat](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CAPTURE_FORMAT.md) | was jede Zeile eines Sitzungslogs enthält und was sich daran niemals ändern wird, mit einem JSON Schema für Tools, die Aufzeichnungen lesen | ## Sicherheit mcpsnoop führt den Server-Befehl aus, den Sie umschließen, also umschließen Sie nur Server, denen Sie vertrauen, und führen Sie nicht vertrauenswürdige in einem Container aus. Es führt niemals etwas aus, das Sie nicht in Ihrer Client-Konfiguration angegeben haben. Für Remote-Workflows verwenden Sie SSH-Tunneling oder SSH-Dateiübertragung, damit Transport-Authentifizierung, Verschlüsselung, Host-Verifizierung, Schlüsselrotation und Audit-Richtlinie in Ihrem bestehenden SSH-Setup bleiben. ### Was ein Capture mit Ihrem Terminal anrichten kann Ein Capture sind Daten, die die andere Seite ausgewählt hat. Frames und stderr-Zeilen können Terminal-Escape-Sequenzen enthalten, und ein Terminal führt aus, was ihm übergeben wird – von einer verzerrten Anzeige bis hin zu OSC 52, das Ihre System-Zwischenablage beschreibt. mcpsnoop behält nur die Farbsequenzen, die es selbst erzeugt, und verwirft jede andere Escape-Sequenz, bevor ein Frame Ihr Terminal erreicht. Tabellenzellen zitieren Steuerzeichen, damit Sie sehen können, dass sie vorhanden waren, der Inspector schreibt sie vollständig aus, und die Zwischenablage-Kopie enthält die escapte Form, sodass Ihnen nichts verborgen bleibt und nichts ausgeführt wird. ### Was ein Capture enthält Erfasste Frames können Prompts, Tool-Argumente, Anmeldedaten und Tool-Ergebnisse enthalten. [docs/REDACTION.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/REDACTION.md) behandelt deren Bereinigung, sowohl während der Erfassung als auch danach. Informationen zum Melden einer Schwachstelle finden Sie in [SECURITY.md](https://github.com/kerlenton/mcpsnoop/blob/main/SECURITY.md). ## Mitwirken Issues und Pull Requests sind willkommen. Details finden Sie in [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/main/CONTRIBUTING.md). ## Lizenz [MIT](https://github.com/kerlenton/mcpsnoop/blob/main/LICENSE)
