跳到主要内容

调试与排错 (Debugging)

开发 MCP Server 时，调试可能比普通 Web 应用略显复杂，因为它运行在受限的子进程或远程 SSE 环境中。本章介绍官方推荐的调试工具与技巧。

1. 使用 MCP Inspector (核心工具)​

MCP Inspector 是官方提供的交互式调试器，它可以模拟 MCP Client，让你在不启动 Claude Desktop 的情况下测试服务器。

安装与启动​

# 不需要安装，直接使用 npx 运行
npx @modelcontextprotocol/inspector <运行服务器的命令>

# 示例：Node.js
npx @modelcontextprotocol/inspector node dist/index.js

# 示例：Python
npx @modelcontextprotocol/inspector python server.py

功能亮点​

  • 可视化面板：直接在浏览器（默认 http://localhost:5173）查看所有 Tools, Resources, Prompts。
  • 实时调用：在页面点击工具并输入参数，直接查看服务器返回的 JSON 内容。
  • 日志追踪：实时查看 JSON-RPC 原始报文，排查格式错误。

2. 检查 Claude Desktop 日志​

如果服务器在 Claude 中无法启动，首要任务是查看日志。

日志文件路径​

  • Windows: %APPDATA%\Claude\logs\mcp.log
  • macOS: ~/Library/Logs/Claude/mcp.log

[!TIP] 开发者可以使用 tail -f (macOS) 或 Get-Content -Wait (Windows) 实时滚动查看日志变化。

3. 常见排错清单​

❌ 现象：服务器在 Claude 中显示为红色图标（启动失败）​

  • Stdio 污染：检查你的代码中是否有非预期的 console.log 或 print。
    • 重要原则：在 Stdio 模式下，stdout 是协议专用通道。任何非 JSON 数据混合进去都会导致 Client 解析失败。
    • 解决方法：所有调试日志必须输出到 stderr（Node.js 使用 console.error，Python 使用 sys.stderr.write）。
  • 路径无效：配置文件中的 args 必须是绝对路径。
  • 环境缺失：Claude 可能无法识别你系统路径里的 npx 或 python。建议在配置文件中使用完整路径。

❌ 现象：改了代码但 Claude 里没反应​

  • 编译缺失：如果你用 TypeScript 编写，记得运行 npm run build 生成最新的 JS 文件。
  • 重启宿主：修改配置文件后，必须通过 Claude 菜单中的 "Restart MCP Servers" 按钮来重载。

4. 高级：远程断点调试​

由于服务器是子进程，你不能直接在 IDE 里通过点击“运行”来调试。

Node.js 方案 (VS Code)​

  1. 在代码中添加环境变量检查： 
    if (process.env.DEBUG) {
       // 可以在此处添加逻辑
    }
  2. 在 claude_desktop_config.json 中添加调试参数： 
    {
      "command": "node",
      "args": ["--inspect=9229", "/path/to/server/index.js"]
    }
  3. 在 VS Code 中使用 "Attach to Process" 连接到 9229 端口进行断点调试。

小结​

  • ✅ Inspector 优先：本地开发阶段 90% 的问题可以在 Inspector 中解决。
  • ✅ 守住 Stdout：只让协议走 stdout，日志全部走 stderr。
  • ✅ 日志为王：养成随时查看 %APPDATA%\Claude\logs 的习惯。