MCP调试教程 - 综合指南与实用工具

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

在开发 MCP 服务器或将其与应用程序集成时，有效的调试是必不可少的。本指南介绍了 MCP 生态系统中可用的调试工具和方法。

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

调试工具概述

MCP 提供了多种工具，用于在不同级别进行调试：

MCP 检查器
- 交互式调试界面
- 直接服务器测试
- 有关详细信息，请参阅 Inspector 指南
Claude 桌面开发人员工具
- 集成测试
- 日志收集
- Chrome DevTools 集成
服务器日志记录
- 自定义日志记录实现
- 错误跟踪
- 性能监控

在 Claude Desktop 中调试

检查服务器状态

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

单击图标可查看：
- 连接的服务器
- 可用的提示和资源
单击图标可查看：
- 可供模型使用的工具

查看日志

查看 Claude Desktop 中的详细 MCP 日志：

## Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

日志捕获：

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

使用 Chrome DevTools

在 Claude Desktop 中访问 Chrome 的开发人员工具以调查客户端错误：

创建一个设置为 true 的文件：developer_settings.json``allowDevTools

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

打开 DevTools：Command-Option-Shift-i

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

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

使用 Console （控制台）面板检查客户端错误。

使用 Network （网络）面板检查：

消息负载
连接计时

常见问题

工作目录

将 MCP 服务器与 Claude Desktop 一起使用时：

通过启动的服务器的工作目录可能未定义（如在 macOS 上），因为 Claude Desktop 可以从任何位置启动claude_desktop_config.json``/
在配置和文件中始终使用绝对路径，以确保可靠运行.env
对于直接通过命令行测试服务器，工作目录将是运行命令的位置

例如，在中，使用：claude_desktop_config.json

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}

而不是像./data

环境变量

MCP 服务器仅自动继承环境变量的子集，如 USER、HOME 和 PATH。

要覆盖默认变量或提供您自己的变量，您可以在：env``claude_desktop_config.json

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

服务器初始化

常见的初始化问题：

路径问题
- 服务器可执行文件路径不正确
- 缺少必需的文件
- 权限问题
- 尝试对command
配置错误
- 无效的 JSON 语法
- 缺少必填字段
- 类型不匹配
环境问题
- 缺少环境变量
- 变量值不正确
- 权限限制

连接问题

当服务器无法连接时：

检查 Claude Desktop 日志
验证服务器进程是否正在运行
使用 Inspector 独立测试
验证协议兼容性

实施日志记录

服务器端日志记录

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

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

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

Python

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

TypeScript

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

要记录的重要事件：

初始化步骤
资源访问
工具执行
错误条件
性能指标

客户端日志记录

在客户端应用程序中：

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

调试工作流

开发周期

初步开发
- 使用 Inspector 进行基本测试
- 实现核心功能
- 添加日志记录点
集成测试
- 在 Claude Desktop 中测试
- 监控日志
- 检查错误处理

测试更改

要有效地测试更改，请执行以下作：

配置更改：重新启动 Claude Desktop
服务器代码更改：使用 Command-R 重新加载
快速迭代：在开发过程中使用 Inspector

最佳实践

日志记录策略

结构化日志记录
- 使用一致的格式
- 包含上下文
- 添加时间戳
- 跟踪请求 ID
错误处理
- 日志堆栈跟踪
- 包括错误上下文
- 跟踪错误模式
- 监视恢复
绩效跟踪
- 日志作计时
- 监控资源使用情况
- 跟踪邮件大小
- 测量延迟

安全注意事项

调试时：

敏感数据
- 清理日志
- 保护凭据
- 屏蔽个人信息
存取控制
- 验证权限
- 检查身份验证
- 监控访问模式

获取帮助

遇到问题时：

第一步
- 检查服务器日志
- 使用 Inspector 进行测试
- 查看配置
- 验证环境
支持渠道
- GitHub 问题
- GitHub 讨论
提供信息
- 日志摘录
- 配置文件
- 重现步骤
- 环境详细信息