mcpsnoop-mcp-debugging

用途

mcpsnoop 是一个针对 Model Context Protocol（MCP）的透明代理，用于实时调试 MCP 客户端与服务器之间的通信流量。它位于 AI 客户端（Claude Desktop、Cursor、Claude Code）与 MCP 服务器之间，拦截双方之间真实的 JSON-RPC 帧，并在终端中实时展示。与官方 MCP Inspector 以独立客户端身份连接的方式不同，mcpsnoop 捕获的是实际客户端与服务器之间的真实流量。

主要能力

mcpsnoop 以两种模式运行：

Shim 模式（mcpsnoop -- <server-command>）：作为客户端与服务器之间的透明代理。
UI 模式（mcpsnoop）：在交互式 TUI 中显示捕获的流量。

Shim 与 UI 通过一个 well-known socket 和磁盘日志通信，因此两者可以以任意顺序启动。

TUI 提供以下操作：

进入帧详情（enter）、返回（esc）
重放选中的工具调用（r）
查看能力协商（c）
复制帧到剪贴板（y）
过滤模式（/）、命令模式（:）
暂停/恢复流（p）、跟随模式（f）
删除会话（ctrl-d）
上下移动（j/k）、前后翻页（ctrl-f/ctrl-b）
跳转顶部/底部（g/G）、显示帮助（?）

过滤语法支持组合 token（以空格分隔，AND 关系），可用过滤器包括：

tool: 按工具名过滤
method: 按 JSON-RPC 方法过滤
id: 按请求/响应 ID 过滤
kind: req（请求）、resp（响应）、notif（通知）
dir: c2s（客户端到服务器）、s2c（服务器到客户端）
status: ok、error、slow、pending

纯文本搜索会匹配方法、工具名、ID 和负载内容。

使用方式

安装

使用 Go：

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

使用 Homebrew：

brew tap kerlenton/mcpsnoop
brew install mcpsnoop

也可从 Releases 页面下载对应平台的预编译二进制文件。

配置（stdio 传输，最常见）

在 MCP 客户端配置文件中包装服务器命令。以 Claude Desktop 为例，macOS 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 编辑 %APPDATA%\Claude\claude_desktop_config.json：

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

-- 之后的内容即正常的服务器启动命令。

Python 服务器示例：

{
  "mcpServers": {
    "weather": {
      "command": "mcpsnoop",
      "args": ["--", "python", "-m", "weather_server"]
    }
  }
}

使用 npx 的 TypeScript 服务器示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "mcpsnoop",
      "args": ["--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    }
  }
}

编译后的二进制示例：

{
  "mcpServers": {
    "custom": {
      "command": "mcpsnoop",
      "args": ["--", "/usr/local/bin/my-mcp-server", "--port", "8080"]
    }
  }
}

HTTP/SSE 传输

对于使用 streamable HTTP 的服务器，将 mcpsnoop 作为反向代理运行：

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

然后将客户端指向 http://localhost:7000。

关键命令

命令	说明
`mcpsnoop`	启动交互式 TUI 查看流量
`mcpsnoop -- <cmd>`	包装服务器命令（shim 模式）
`mcpsnoop http`	启动 HTTP 反向代理
`mcpsnoop demo`	运行脚本化演示会话
`mcpsnoop --help`	显示所有选项

高级用法

自定义日志目录：

mcpsnoop --log-dir /custom/path

在 shim 模式下过滤（减少磁盘占用）：

mcpsnoop --filter tool:search -- python server.py

导出会话（会话以 JSONL 存储）：

cat ~/.config/mcpsnoop/sessions/*.jsonl | jq .

适用场景

调试未被调用的工具：配置 mcpsnoop 包装器、重启客户端、打开 TUI、按 c 查看能力、验证工具是否在服务器能力中列出、检查客户端是否接受该能力、使用 /tool:your_tool_name 过滤、在客户端尝试使用该工具、查找 PENDING 状态（表示挂起调用）或调用缺失。
检查能力协商：按 c 查看能力屏幕，在客户端能力、服务器能力与握手详情之间导航。
重放工具调用：在 TUI 中导航到 tools/call 请求，按 r 重放；mcpsnoop 会启动一个全新的隔离服务器实例，执行完全相同的调用并显示新响应。适用于无需重启客户端即可测试修复、对比代码变更后的响应、调试非确定性行为。
监控慢工具：使用 /status:slow 仅显示慢调用（阈值可配置），每个帧显示耗时，PENDING 调用显示实时计时器。
调试服务器 stderr：服务器 stderr 会以特殊高亮出现在流中，可用 /kind:notif 过滤。
多服务器设置：在配置中为多个服务器分别包装 mcpsnoop，TUI 会以独立会话显示所有服务器，使用 :sessions 命令切换。
CI/CD 集成：mcpsnoop 日志为结构化 JSONL，适合自动化测试，例如 jq 'select(.kind == "response" and .status == "error")' test-logs/*.jsonl。

限制与注意事项

mcpsnoop 增加的延迟极小（复制帧为微秒级），磁盘 I/O 为异步缓冲。
大负载（超过 1MB）可能拖慢 TUI 渲染，建议在繁忙系统中使用过滤器减少噪音。
重放可能因服务器存在状态依赖、外部资源不可用或非幂等操作而失败；此时应检查重放输出中的 stderr 并对比请求参数。
若 UI 显示“No sessions”，通常是因为 shim 尚未启动或客户端尚未启动服务器；需确认 mcpsnoop 已在客户端配置中、完全重启 AI 客户端、触发 MCP 动作以启动服务器，并等待几秒后刷新 UI。
若工具调用挂起（显示 PENDING），应检查帧列表中的服务器 stderr、按 enter 查看完整请求、查找资源锁或外部 API 超时，并按 r 以调试日志重放。
若服务器未启动，可直接测试服务器命令、检查 mcpsnoop 能否找到命令、查看客户端日志（Claude Desktop 为 ~/Library/Logs/Claude/）。
若能力不匹配（客户端看不到服务器声明的工具），按 c 对比服务器能力与客户端能力、检查服务器的 initialize 响应、验证工具 schema 是否符合 MCP 规范。
若帧未出现在 TUI 中，检查 socket 连接（Linux/macOS 为 ls -la ~/.config/mcpsnoop/）、日志目录中的 .jsonl 文件、shim 的日志写入权限，并可运行 mcpsnoop demo 验证 TUI 是否正常。

技能介绍

用途