内容
# mcpsnoop
**适用于 MCP 的 Wireshark**。一个透明的代理，实时显示 AI 客户端和 MCP 服务器之间每个真实的工具调用，显示在终端中。
[](https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/kerlenton/mcpsnoop)
[](LICENSE)
## 问题
官方 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 作为其自己的客户端连接。它从未见过 *您的* 客户端（Claude Desktop、Cursor、Claude Code）和您的服务器之间的流量。因此，当工具无声地未被调用、功能不匹配或调用卡住时，您又回到了 `/tmp` 中 `tail` 日志并进行猜测。
mcpsnoop 而是坐在实际的数据路径中。将其与您的服务器命令一起包装，每个 JSON-RPC 帧都显示在实时终端 UI 中：工具调用、参数、响应、计时、错误以及双方实际协商的功能。您还可以重放任何捕获的调用，而无需再次驱动整个客户端。
## 快速开始
在客户端的 MCP 配置中包装您的服务器：
```jsonc
{ "mcpServers": {
"my-server": { "command": "mcpsnoop", "args": ["--", "node", "build/index.js"] }
}}
```
像平常一样使用您的客户端，然后打开 UI：
```bash
mcpsnoop
```
无需标志，无需套接字路径，无需记住启动顺序。shim 和 UI 彼此自动查找，UI 从磁盘回填过去的会话，因此无论您在客户端之前还是之后打开它，都无关紧要。
对于可流式 HTTP 服务器，运行 mcpsnoop 作为反向代理，并将您的客户端指向它：
```bash
mcpsnoop http --target http://localhost:3000/mcp --listen :7000
```
没有自己的测试服务器？ [docs/DEMO.md](docs/DEMO.md) 介绍了通过 mcpsnoop 将 Claude 指向发布的测试服务器。
## 功能
- **实时 JSON-RPC 流**。请求、响应、通知和服务器 stderr，颜色编码，错误和慢速调用突出显示。
- **重放**。针对全新、隔离的服务器重新运行任何捕获的工具调用。迭代工具的最快循环。
- **功能检查器** (`c`)。查看客户端和服务器在握手时实际同意的内容。
- **帧检查器** (`enter`)。完整的、漂亮的 JSON，帧内搜索。
- **挂起调用检测**。进行中请求显示 `PENDING` 并带有实时计时器，因此卡住的工具一眼可见。
- **真正的过滤查询**。使用 `tool:`、`status:`、`dir:`、`kind:`、`id:` 或纯文本缩小流。
- **工具级错误**。带有 `result.isError: true` 的响应被标记，而不仅仅是 JSON-RPC 错误。
- **复制** (`y`) 任何帧的 JSON 直接到剪贴板。
- **多个服务器** 同时，每个服务器都在自己的会话中。
- **stdio 和流式 HTTP** （JSON 和 SSE）。
- **单个静态二进制文件，无运行时依赖**。
## 比较
| | MCP Inspector | mcp-trace | mcpsnoop |
|---|:---:|:---:|:---:|
| 看见您真正的客户端↔服务器流量 | 否 | 是 | 是 |
| 交互式终端 UI | 否 | 是 | 是 |
| 零配置，无标志或排序 | 否 | 否 | 是 |
| 功能检查器 | 部分 | 否 | 是 |
| 重放捕获的调用 | 否 | 否 | 是 |
| 单个二进制文件，无运行时依赖 | 否 | 取决于 | 是 |
## 安装
```bash
go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest
```
或者，从 [Releases](https://github.com/kerlenton/mcpsnoop/releases) 页面为您的平台获取预构建的二进制文件。
从源代码：
```bash
git clone https://github.com/kerlenton/mcpsnoop && cd mcpsnoop
go build -o mcpsnoop ./cmd/mcpsnoop
```
## 工作原理
```
stdio / HTTP stdio / HTTP
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ AI 客户端 │──────▶│ mcpsnoop -- │──────▶│ MCP 服务器 │
│ Claude, Cursor… │◀──────│ 透明 shim │◀──────│ 您自己的，或任何 │
└──────────────────┘ └─────────┬────────┘ └──────────────────┘
│ 每个 JSON-RPC 帧的副本
▼
┌──────────────────┐
│ mcpsnoop │ ← 您实时查看此内容
│ 实时终端 UI │
└──────────────────┘
```
客户端是驱动对话的任何内容（Claude Desktop、Cursor、Claude Code、您自己的代理）。服务器是任何 MCP 服务器，使用任何语言，通过 stdio 或流式 HTTP。官方 Inspector 连接为 *第二个* 客户端，旁边；mcpsnoop 坐在实际的管道中，因此它看到您的真实客户端和服务器之间的内容。
mcpsnoop 是单个二进制文件中的两个角色。
`mcpsnoop -- <server>` 是一个透明的 stdio shim，您的客户端启动它来代替服务器。它转发字节原样（它永远不会损坏管道），同时将每个 JSON-RPC 帧的副本发送到中心，并且还写入磁盘的每个会话日志。
不带参数的 `mcpsnoop` 是中心和 TUI。它监听一个众所周知的套接字，将请求与响应配对以得出计时，解析工具调用和功能，并实时渲染所有内容。
因为日志在磁盘上，套接字是众所周知的，所以任一方都不必先启动。
## 快捷键
**导航**
| 键 | 操作 |
|---|---|
| `j` / `k` （或 `↑` / `↓`）| 向下 / 向上移动 |
| `ctrl-f` / `ctrl-b` | 向下 / 向上翻页 |
| `g` / `G` | 跳转到顶部 / 底部 |
| `shift`+列 | 按该列排序（再次按以反转） |
**在视图之间移动**
| 键 | 操作 |
|---|---|
| `enter` | 深入到选定的会话，或打开帧检查器 |
| `esc` | 退回到上一级 |
| `:` | 命令提示符（`：sessions`、`：stream`、`：q` 等） |
| `?` | 帮助 |
| `:q` | 退出 |
**对选定内容采取行动**
| 键 | 操作 |
|---|---|
| `r` | 重放选定的调用到新的、隔离的服务器 |
| `c` | 功能检查器 |
| `y` | 将帧的 JSON 复制到剪贴板 |
| `p` | 暂停 / 恢复实时流 |
| `f` | 切换跟随（自动滚动到最新帧） |
| `ctrl-d` | 删除选定的会话 |
**过滤和搜索**
| 键 | 操作 |
|---|---|
| `/` | 过滤当前表（流支持查询语言 - 参见下文） |
| `/` 在帧中 | 在打开的帧中搜索；`n` / `N` 跳转到匹配项之间 |
## 过滤流
在会话中，按 `/` 并组合空格分隔的标记 - 它们是 ANDed 的，因此每个标记进一步缩小流。
| 标记 | 匹配 | 示例 |
|---|---|---|
| `<text>` | 方法、工具名称、id 和原始 JSON 有效载荷上的子字符串 | `searchFiles` |
| `tool:<name>` | `tools/call` 的工具 | `tool:echo` |
| `method:<name>` | JSON-RPC 方法 | `method:tools/list` |
| `id:<n>` | 确切的请求 id | `id:7` |
| `kind:<type>` | 消息类型：`req`、`resp`、`notify`、`stderr` | `kind:resp` |
| `dir:<way>` | 方向：`c2s`（客户端→服务器）或 `s2c`（服务器→客户端） | `dir:s2c` |
| `status:<state>` | 结果：`ok`、`err`、`slow`、`pending` | `status:err` |
例如，`tool:search status:slow` 仅显示对搜索工具的慢速调用，而 `dir:s2c kind:req` 显示服务器发起的请求（采样、根）。
## 安全
mcpsnoop 运行您包装的服务器命令，因此请仅包装您信任的服务器，并在容器中运行不受信任的服务器。它从不执行您未在客户端配置中放置的内容。
## 贡献
问题和拉取请求是欢迎的 - 有关开发设置和 `make check` 门控，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。mcpsnoop 是 pre-1.0 并遵循 [SemVer](https://semver.org)：在 `0.x` 上，次要版本可能会更改用户界面行为，而补丁版本是错误修复。
## 许可证
[MIT](LICENSE)
