mcpsnoop CLI
A transparent proxy between an AI client and an MCP server: shows every JSON-RPC frame in the terminal, checks a capture in CI and exports spans
- 367 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Sees the entire exchange between a client and an MCP server, including call arguments, responses and authorization headers, and writes it to disk
- Rewrites the Claude Desktop configuration with wrap and acts as a proxy in front of a server
- OpenTelemetry export and the GitHub Action send recorded data to external systems
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mcpsnoopDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Sees the entire exchange between a client and an MCP server, including call arguments, responses and authorization headers, and writes it to disk
- Rewrites the Claude Desktop configuration with wrap and acts as a proxy in front of a server
- OpenTelemetry export and the GitHub Action send recorded data to external systems
This is third-party code. Review the repository files before installing.
What it does
mcpsnoop sits in the pipe between your AI client and an MCP server and records every JSON-RPC frame without changing either side. The author calls it Wireshark for MCP. The official MCP Inspector connects as its own client, so it does not see what Cursor, Claude Code or Codex actually send a server and cannot show a call the model never made or made with wrong arguments. mcpsnoop sits in the real data path. Starting is simple. In the client config the server command is wrapped like this: `mcpsnoop -- node build/index.js`, and then the `mcpsnoop` command with no arguments opens the terminal interface. For Claude Desktop `mcpsnoop wrap my-server` edits the settings file itself and keeps a backup, while `mcpsnoop unwrap` puts everything back. For a Streamable HTTP server the reverse proxy `mcpsnoop http --target http://localhost:3000/mcp --listen :7000` works, and response statuses, including 401 and 403, appear in the stream. The engineering part follows. `mcpsnoop check` fails a CI build on errors, broken result schemas, hung or twice-run calls and changes to tool definitions, and `mcpsnoop replay` replays a recorded client session against every build with no model or API key. `mcpsnoop export` produces json, html, har and OpenTelemetry spans following the MCP conventions; there are Prometheus metrics and a GitHub Action that sends findings to the repository's security tab. The `mock`, `diff`, `stats` and `clients` commands help compare sessions and clients.
Who it is for. For MCP server authors and engineers who connect servers in Cursor, Claude Code and Codex and want to see the real exchange and catch regressions in CI.
Good fit when
- A tool on your server is silently never called by the model and you need to see what the client actually sent
- Client and server capabilities diverge or a call hangs, and the logs are empty
- You want to record one session with a real client, commit it and replay it against every CI build with no model
- You need to detect whether a server's tool definitions changed after an update and fail the build on a mismatch
- You want MCP calls as OpenTelemetry spans in your tracing system or as Prometheus metrics
Not a fit when
- You want to try a server by hand from a browser: the official MCP Inspector, which works as a separate client, suits that
- You need to scan servers and skills for prompt injection and vulnerabilities before installing: mcpsnoop watches operation and does not analyze definitions up front
- You cannot change the client configuration: to put mcpsnoop in the pipe the server command has to be wrapped
- You want to proxy a remote OAuth server's traffic: the tool shows the 401 header but does not replace an authorization client
Example request
Wrap my MCP server in mcpsnoop, run a session in Claude Code and show which tool calls the client actually sent and whether any had errorsLimitations
- For a stdio server the command must be wrapped in the client configuration, and Claude Desktop must be restarted after the edit because MCP servers launch once at startup.
- `mcpsnoop wrap` rewrites one server's entry in claude_desktop_config.json, and the key order inside it becomes alphabetical. A backup is kept alongside.
- The GitHub Action needs the security-events: write permission, otherwise the report upload returns 403. In a repository without code scanning, turn the upload off with the upload-sarif parameter.
- The action version is pinned by hand: there is no floating v1 tag. When a check cannot run, the job ends with an error.
- Sessions are stored on disk, and `mcpsnoop prune` clears old records.
How to disable. Restore the server command in the client configuration without the wrapper, or run `mcpsnoop unwrap my-server` for Claude Desktop: the settings file is restored from the backup, and the backup is removed once no wrapped servers remain. Then restart the client. The installed program is removed by your package manager, for example `npm uninstall -g mcpsnoop` or `brew uninstall mcpsnoop`.
FAQ
How do I attach mcpsnoop to an MCP server in Claude Desktop?
Run mcpsnoop wrap my-server: it finds claude_desktop_config.json, makes a backup and rewrites only that server's entry. Then restart Claude Desktop and open the interface with mcpsnoop. mcpsnoop unwrap my-server puts everything back.
How is mcpsnoop different from MCP Inspector?
MCP Inspector connects to a server as its own client and sees only its own calls. mcpsnoop sits between your real client and the server, so it shows what Cursor, Claude Code or Codex actually send, including a call the model never made or made with wrong arguments.
How do I test an MCP server in CI with mcpsnoop?
Record one session with a real client, commit the file and add the kerlenton/mcpsnoop action with the replay and server parameters. It replays the session against every build with no model or API key, checks the result and fails the job if the server got worse than in the recording.
How do I watch the traffic of an HTTP server?
Run the reverse proxy mcpsnoop http --target http://localhost:3000/mcp --listen :7000 and point the client at port 7000. Response statuses show in the stream, including 401 with the WWW-Authenticate header and 403 for a rejected Origin. The status:401 and status:err filters narrow the list in the interface.
Can mcpsnoop data go to a tracing system?
Yes. mcpsnoop export -T otlp -o trace.json builds spans from a capture, and the --otlp-endpoint flag sends them as calls complete. A tool call arrives as a span like tools/call search with the mcp.method.name and gen_ai.tool.name attributes. --metrics-listen enables Prometheus metrics.
Discussion
No questions or reviews yet.
Related
CLI toolsA command-line debugger for MCP servers from Giant Swarm: a REPL for tools, OAuth 2.1 and an MCP server mode for Cursor
An MCP server that builds a code graph once and serves the answer to the agent instead of re-reading files
A local tool to test and debug MCP servers: chat with tools, inspect calls and run evals across clients
Command-line inspector for HTTP MCP servers: lists tools, schemas, prompts and resources and calls any tool by hand.
The openmcp CLI and a VS Code extension for debugging MCP servers: tools, prompts and resources, chat with a model, test cases
An async Python MCP client with a CLI and web UI that connects Claude to servers over stdio and SSE.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| mcpsnoop (this card) | no | 367 | ||
| MCP Scanner | yes | 1,109 | Cisco's static MCP server scanner that does not watch a live client's calls | |
| Charles MCP Server | no | API key | 330 | an MCP server for Charles Proxy where the agent reads HTTP traffic, with no MCP frames |
README in short
The README explains the MCP debugging problem and shows CI use, OpenTelemetry export and a quick start. It then covers installation through npm, Homebrew and Go, a command table, a comparison with Inspector, Snyk Agent Scan, MCP Observatory and mcprec, an architecture sketch and a detailed section on the GitHub Action.