kerlenton/mcpsnoop

来源：https://github.com/kerlenton/mcpsnoop

Wireshark for MCP（模型上下文协议）。一个透明代理，能在终端实时显示你的 AI 客户端与 MCP 服务器之间的每一次真实工具调用。

CI（https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml）
Go 参考文档（https://pkg.go.dev/github.com/kerlenton/mcpsnoop）
MIT

demo

问题所在

官方 MCP Inspector（https://github.com/modelcontextprotocol/inspector）以独立的客户端身份连接，它永远看不到 你的 客户端（Claude Desktop、Cursor、Claude Code）与服务器之间的流量。在你自己的服务器上设置断点，也只能在请求到达时触发一次，无法展示真实客户端从未发出过的调用，或因参数出乎意料而发起的调用。

因此，当某个工具静默地未被调用、能力不匹配，或调用直接挂起时，你又只能回到 /tmp 里 tail 日志并靠猜测。mcpsnoop 则直接置于真实数据路径中，让你能调试客户端与服务器之间实际的 MCP 流量。用它包装你的服务器命令，然后在实时终端 UI 中观看你的真实客户端和服务器对话时的每一个 JSON-RPC 帧。

快速开始

想先看效果，无需任何设置？运行 mcpsnoop demo 即可看到一个脚本化会话在实时 UI 中播放。

要实际使用，只需在你的客户端 MCP 配置中用 mcpsnoop 包装你的服务器：

{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

-- 之后的所有内容就是你通常启动服务器的命令（此处是用 node 运行 TypeScript 构建产物）。换成你正在使用的任何命令，例如 python server.py、npx -y @scope/server 或一个编译好的二进制文件。

像往常一样使用你的客户端，然后打开 UI：

mcpsnoop

无需标志、无需 socket 路径、无需记住启动顺序。shim 和 UI 会自动找到彼此，而且 UI 会从磁盘回填之前的会话，所以无论你是在客户端之前还是之后打开它都没关系。

对于可流式 HTTP 服务器，将 mcpsnoop 作为反向代理运行，并将客户端指向它：

mcpsnoop http --target http://localhost:3000/mcp --listen :7000

没有自己的服务器可测试？docs/DEMO.md 介绍了如何通过 mcpsnoop 将 Claude 指向一个已公开的测试服务器。

特性

• 实时 JSON-RPC 流。 请求、响应、通知和服务器 stderr，彩色显示，错误和慢调用会被标记，包括工具级别的 result.isError，而不仅仅是 JSON-RPC 错误。
• 回放。 针对一个新鲜的、隔离的服务器副本，重新运行任何捕获到的工具调用。这是在工具上迭代的最快循环。
• 能力检查器（c）。 精确查看客户端和服务器在握手时协商了哪些能力。
• 帧检查器（enter）。 完整的、格式化良好的 JSON，支持帧内搜索。
• 挂起调用检测。 正在进行的请求显示为 PENDING 并带有实时计时器，因此卡住的工具一目了然。
• 真正的过滤查询。 使用 tool:、status:、dir:、kind:、id: 或纯文本来缩小流范围。

对比

| | MCP Inspector | mcp-trace | mcpsnoop | |—|—|:—:|:—:|:—:| | 能看到真实客户端↔服务器流量 | 否 | 是 | 是 | | 交互式终端 UI | 否 | 是 | 是 | | 零配置，无需标志或顺序 | 否 | 否 | 是 | | 能力检查器 | 部分 | 否 | 是 | | 回放捕获的调用 | 否 | 否 | 是 | | 单一二进制，无运行时依赖 | 否 | 不定 | 是 |

安装

go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest

或者使用 Homebrew（https://brew.sh）：

brew tap kerlenton/mcpsnoop
brew install mcpsnoop

较新版本的 Homebrew 会对第三方 tap 进行门控；如果拒绝，请先用 brew trust kerlenton/mcpsnoop 信任该 tap，然后重新运行安装命令。免 tap 的 brew install mcpsnoop（无需 tap，无需信任）需要 Homebrew core，而 core 只接受超过一定知名度门槛（星标、fork、关注数）的项目。如果你觉得这很方便，在 repo 上点个星标有助于它达到标准。

或者从 Releases（https://github.com/kerlenton/mcpsnoop/releases）页面为你的平台获取预构建二进制文件。

工作原理

官方 Inspector 作为一个第二个客户端在旁边连接。mcpsnoop 则位于实际的管道中，因此它能看到你的真实客户端和服务器之间所说的每一句话，无论服务器用什么语言编写。它在同一个二进制文件中承担两个角色：mcpsnoop -- <your server> 是客户端启动的透明 shim（逐字节转发，同时发送每个帧的副本），而无需参数的 mcpsnoop 是中心枢纽和 TUI。它们通过一个众所周知的 socket 和磁盘上的日志配对，因此两者都不需要先启动。

快捷键

enter 深入查看 · esc 返回 · r 回放 · c 能力 · y 复制 · / 过滤 · : 命令 · p 暂停 · f 跟随 · ctrl-d 删除。使用 j/k 移动，ctrl-f/ctrl-b 翻页，g/G 跳转到顶部/底部，shift+列排序。在应用中按 ? 查看完整列表。

过滤流

在会话中，按 / 并组合用空格分隔的 token（AND 逻辑）：纯文本匹配方法、工具、id 和 payload，而 tool:、method:、id:、kind:、dir:、status: 按字段过滤。因此 tool:search status:slow 显示对搜索工具的慢调用，而 dir:s2c kind:req 显示服务器发起的请求（采样、根列表）。? 帮助列出了每个 token 及其接受的值。

安全性

mcpsnoop 会运行你包装的服务器命令，因此只包装你信任的服务器，并在容器中运行不信任的服务器。它永远不会执行你未放入客户端配置中的任何内容。

贡献

欢迎提交 issue 和 pull request。查看 CONTRIBUTING.md 了解开发设置和 make check 门控。mcpsnoop 是 1.0 之前的版本，遵循 SemVer（https://semver.org）：在 0.x 期间，次要版本可能会改变用户可见行为，补丁版本是 bug 修复。

许可证

MIT