调试

调试模型上下文协议（MCP）集成的综合指南

在开发 MCP 服务器或将其与应用程序集成时，有效的调试至关重要。本指南涵盖了 MCP 生态系统中可用的调试工具和方法。

本指南适用于 macOS。其他平台的指南即将推出。

调试工具概述

MCP 提供了几个不同级别的调试工具：

1. MCP 检查器

   • 交互式调试界面
   • 直接服务器测试
   • 详细信息请参阅检查器指南

2. Claude 桌面开发者工具

   • 集成测试
   • 日志收集
   • Chrome DevTools 集成

3. 服务器日志记录

   • 自定义日志实现
   • 错误跟踪
   • 性能监控

在 Claude 桌面版中调试

检查服务器状态

Claude.app 界面提供基本的服务器状态信息：

1. 点击 图标查看：

   • 已连接的服务器
   • 可用的提示和资源

2. 点击 图标查看：

   • 提供给模型的工具

查看日志

从 Claude 桌面版查看详细的 MCP 日志：

# 实时跟踪日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

日志捕获：

• 服务器连接事件
• 配置问题
• 运行时错误
• 消息交换

使用 Chrome DevTools

在 Claude 桌面版中访问 Chrome 的开发者工具以调查客户端错误：

1. 启用 DevTools：

jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json

2. 打开 DevTools：Command-Option-Shift-i

注意：您将看到两个 DevTools 窗口：

• 主内容窗口
• 应用程序标题栏窗口

使用 Console 面板检查客户端错误。

使用 Network 面板检查：

• 消息负载
• 连接时间

常见问题

工作目录

在 Claude 桌面版中使用 MCP 服务器时：

• 通过 claude_desktop_config.json 启动的服务器的工作目录可能未定义（如 macOS 上的 /），因为 Claude 桌面版可以从任何地方启动
• 始终在配置和 .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. 使用检查器独立测试
4. 验证协议兼容性

实现日志记录

服务器端日志记录

在构建使用本地 stdio 传输的服务器时，所有记录到 stderr（标准错误）的消息将自动由主机应用程序（例如 Claude 桌面版）捕获。

本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议操作。

对于所有传输，您还可以通过发送日志消息通知向客户端提供日志记录：

Python

server.request_context.session.send_log_message(
  level="info",
  data="Server started successfully",
)

重要事件记录：

• 初始化步骤
• 资源访问
• 工具执行
• 错误情况
• 性能指标

客户端日志记录

在客户端应用程序中：

1. 启用调试日志记录
2. 监控网络流量
3. 跟踪消息交换
4. 记录错误状态

调试工作流程

开发周期

1. 初始开发

   • 使用检查器进行基本测试
   • 实现核心功能
   • 添加日志记录点

2. 集成测试

   • 在 Claude 桌面版中测试
   • 监控日志
   • 检查错误处理

测试更改

高效测试更改：

• 配置更改：重启 Claude 桌面版
• 服务器代码更改：使用 Command-R 重新加载
• 快速迭代：在开发过程中使用检查器

最佳实践

日志记录策略

1. 结构化日志记录

   • 使用一致的格式
   • 包含上下文
   • 添加时间戳
   • 跟踪请求 ID

2. 错误处理

   • 记录堆栈跟踪
   • 包含错误上下文
   • 跟踪错误模式
   • 监控恢复

3. 性能跟踪

   • 记录操作时间
   • 监控资源使用
   • 跟踪消息大小
   • 测量延迟

安全考虑

调试时：

1. 敏感数据

   • 清理日志
   • 保护凭据
   • 掩盖个人信息

2. 访问控制

   • 验证权限
   • 检查身份验证
   • 监控访问模式

获取帮助

遇到问题时：

1. 第一步

   • 检查服务器日志
   • 使用检查器测试
   • 查看配置
   • 验证环境

2. 支持渠道

   • GitHub 问题
   • GitHub 讨论

3. 提供信息

   • 日志摘录
   • 配置文件
   • 重现步骤
   • 环境详细信息

下一步

MCP 检查器

学习使用 MCP 检查器