在开发MCP服务器或将其与应用程序集成时，有效的调试至关重要。本指南介绍了MCP生态系统中可用的调试工具和方法。
本指南适用于macOS。其他平台的指南即将推出。

​
调试工具概览

MCP 提供多种工具用于不同层次的调试：
  1. MCP 检查员
    • 交互式调试界面
    • 直接服务器测试
    • 查看Inspector guide获取详细信息
  2. Claude桌面开发者工具
    • 集成测试
    • 日志收集
    • Chrome DevTools 集成
  3. 服务器日志记录
    • 自定义日志记录实现
    • 错误追踪
    • 性能监控

​
调试Claude桌面端

​
检查服务器状态

Claude.app界面提供基础的服务器状态信息：
  1. 点击 图标查看：
    • 已连接的服务器
    • 可用的提示和资源
  2. 点击“搜索和工具”图标查看：
    • 模型可用的工具

​
查看日志

查看来自 Claude Desktop 的详细 MCP 日志: 
# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
日志捕获内容：
  • 服务器连接事件
  • 配置问题
  • 运行时错误
  • 信息交换

​
使用Chrome开发者工具

在Claude Desktop中访问Chrome开发者工具来调查客户端错误：
  1. 创建一个 developer_settings.json 文件，并将 allowDevTools 设置为 true：
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
  1. 打开开发者工具：Command-Option-Shift-i
注意：您会看到两个 DevTools 窗口：
  • 主内容窗口
  • 应用标题栏窗口
使用控制台面板来检查客户端错误。 使用Network面板检查:
  • 消息载荷
  • 连接时序

​
常见问题

​
工作目录

当使用MCP服务器与Claude桌面版时：
  • 通过claude_desktop_config.json启动的服务器，其工作目录可能未定义（如macOS上的/），因为Claude Desktop可以从任何位置启动
  • 始终在配置文件和.env文件中使用绝对路径，以确保可靠的运行
  • 测试通过命令行直接访问服务器时，工作目录将是运行命令的位置
例如在 claude_desktop_config.json 中，使用： 
{
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/Users/username/data"
  ]
}
使用相对路径例如 ./data 替代

​
环境变量

MCP 服务器仅自动继承一部分环境变量，例如 USER、HOME 和 PATH。 要覆盖默认变量或提供您自己的变量，您可以在claude_desktop_config.json中指定一个env键： 
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key"
    }
  }
}

​
服务端初始化

常见初始化问题：
  1. 路径问题
    • 服务器可执行文件路径错误
    • 缺少必要文件
    • 权限问题
    • 尝试为 command 使用绝对路径
  2. 配置错误
    • 无效的JSON语法
    • 缺失必填字段
    • 类型不匹配
  3. 环境问题
    • 缺少环境变量
    • 变量值不正确
    • 权限限制

​
连接问题

<提示>当服务器连接失败时：
  1. 检查Claude桌面日志
  2. 验证服务器进程正在运行
  3. 使用 Inspector 进行独立测试
  4. 验证协议兼容性

​
实施日志记录

​
服务端日志记录

当构建使用本地标准输入输出传输的服务器时，所有记录到标准错误输出的消息都会被主机应用程序（例如Claude Desktop）自动捕获。
本地MCP服务器不应将日志消息输出到stdout（标准输出），因为这会干扰协议操作。
对于所有传输方式，您还可以通过发送日志消息通知来为客户端提供日志功能： 
server.request_context.session.send_log_message(
  level="info",
  data="Server started successfully",
)
重要事件记录：
  • 初始化步骤
  • 资源访问
  • 工具执行
  • 错误条件
  • 性能指标

​
客户端日志记录

在客户端应用中：
  1. 启用调试日志
  2. 监控网络流量
  3. 追踪消息交换
  4. 记录错误状态

​
调试工作流

​
开发周期

  1. 初始开发
    • 使用 Inspector 进行基本测试
    • 实现核心功能
    • 添加日志点
  2. 集成测试
    • 在Claude桌面端测试
    • 监控日志
    • 检查错误处理

​
测试变更

要高效测试更改：
  • 配置更改：重启Claude桌面应用
  • 服务器代码改动：使用 Command-R 重新加载
  • 快速迭代: 在开发过程中使用 Inspector

​
最佳实践

​
日志记录策略

  1. 结构化日志记录
    • 使用一致的格式
    • 包含上下文
    • 添加时间戳
    • 追踪请求ID
  2. 错误处理
    • 记录堆栈跟踪
    • 包含错误上下文
    • 追踪错误模式
    • 监控恢复情况
  3. 性能追踪
    • 记录操作时间
    • 监控资源使用情况
    • 追踪消息大小
    • 测量延迟

​
安全注意事项

调试时：
  1. 敏感数据
    • 清理日志
    • 保护凭据
    • 屏蔽个人信息
  2. 访问控制
    • 验证权限
    • 检查认证
    • 监控访问模式

​
获取帮助

遇到问题时：
  1. 初始步骤
    • 检查服务器日志
    • 使用Inspector进行测试
    • 检查配置
    • 验证环境
  2. 支持渠道
    • GitHub 问题
    • GitHub 讨论
  3. 提供信息
    • 日志摘录
    • 配置文件
    • 重现步骤
    • 环境详细信息

​
后续步骤

MCP 检查器

学会使用MCP检查器