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

​
调试工具概述

MCP 提供了多种在不同层级进行调试的工具：
  1. MCP 检查器：交互式、与传输无关的测试 UI。连接到 stdio 或 Streamable HTTP 服务器，调用 工具、提示词 和 资源，并观察通知流。这应该是你的首选工具。
  2. 服务器日志：结构化日志输出到 stderr（stdio 传输）或通过 notifications/message（所有传输）。
  3. 客户端开发者工具：大多数 MCP 客户端都会暴露日志和连接状态。参见下方的 在 Claude Desktop 中调试 作为一个示例，或查阅你的客户端文档。

​
实现日志记录

​
服务器端日志记录

当构建使用本地 stdio 传输 的服务器时，所有记录到 stderr（标准错误）的消息将由宿主应用程序自动捕获。
本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议操作。
对于使用 Streamable HTTP 传输 的服务器，客户端不会捕获 stderr。请使用下方的日志消息通知、你自己的服务器端日志聚合，或标准 HTTP 工具（curl、浏览器 DevTools Network 面板）来检查请求、Mcp-Session-Id headers 和 SSE 流。 对于所有 传输，你还可以通过发送日志消息通知向客户端提供日志记录： 
@server.tool()
async def my_tool(ctx: Context) -> str:
    await ctx.session.send_log_message(
        level="info",
        data="Server started successfully",
    )
    return "done"
MCP 定义了八个 RFC 5424 严重性级别（debug 到 emergency）。客户端可以通过 logging/setLevel 请求在运行时调整最低级别。 需要记录的重要事件：
  • 初始化步骤
  • 资源访问
  • 工具执行
  • 错误条件
  • 性能指标

​
常见问题

下面的示例使用 Claude Desktop 的 claude_desktop_config.json；同样的原则适用于任何基于 stdio 的 MCP 客户端。

​
工作目录

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

​
环境变量

通过 stdio 启动的 MCP 服务器仅自动继承有限的环境变量子集（确切集合取决于平台）。 要覆盖默认变量或提供你自己的变量，你可以在 claude_desktop_config.json 中指定 env 键： 
{
  "mcpServers": {
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

​
服务器初始化

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

​
连接问题

当服务器无法连接时：
  1. 检查客户端日志
  2. 验证服务器进程是否正在运行
  3. 使用 检查器 独立测试
  4. 验证 协议兼容性
  5. 检查 能力协商：错误 -32602 是标准的 JSON-RPC “无效参数” 代码，并在许多上下文中返回。一个常见的原因是服务器向未声明该能力的客户端发送 采样 或 征询 请求。检查 initialize 交换 以验证双方都声明了你预期的内容

​
在 Claude Desktop 中调试

Claude Desktop 是 众多 MCP 客户端之一。它可在 macOS 和 Windows 上使用。

​
检查服务器状态

点击聊天输入框中的 “Add files, connectors, and more” 加号图标，然后悬停在 Connectors 菜单上以查看连接的服务器和可用工具。 可用的 MCP 工具

​
查看日志

日志文件写入到：
  • macOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\logs
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
日志捕获：
  • 服务器连接事件
  • 配置问题
  • 运行时错误
  • 消息交换

​
使用 Chrome DevTools

在 Claude Desktop 内部访问 Chrome 开发者工具以调查客户端错误：
  1. 创建一个 developer_settings.json 文件，将 allowDevTools 设置为 true：
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
  1. 打开 DevTools：Command-Option-I (macOS) 或 Ctrl+Alt+I (Windows)
注意：你将看到两个 DevTools 窗口：
  • 主内容窗口
  • 应用程序标题栏窗口
使用 Console 面板检查客户端错误。 使用 Network 面板检查：
  • 消息负载
  • 连接计时

​
调试工作流

​
开发周期

  1. 初始开发
    • 使用 检查器 进行基本测试
    • 实现核心功能
    • 添加日志记录点
  2. 集成测试
    • 在你的目标 MCP 客户端中测试
    • 监控日志
    • 检查错误处理

​
测试更改

为了有效地测试更改：
  • 配置更改：重启 MCP 客户端
  • 服务器代码更改：重启客户端（对于 Claude Desktop，完全退出并重新打开；仅关闭窗口是不够的）
  • 快速迭代：在开发期间使用 检查器

​
最佳实践

​
日志记录策略

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

​
安全注意事项

调试时：
  1. 敏感数据
    • 清理日志
    • 保护凭据
    • 掩盖个人信息
  2. 访问控制
    • 验证权限
    • 检查身份验证
    • 监控访问模式
有关 MCP 攻击向量和缓解措施的完整处理，请参阅 安全最佳实践。

​
获取帮助

遇到问题时：
  1. 第一步
    • 检查服务器日志
    • 使用 检查器 测试
    • 审查配置
    • 验证环境
  2. 支持渠道
  3. 提供信息
    • 日志摘录
    • 配置文件
    • 复现步骤
    • 环境详情

​
下一步

MCP 检查器

学习使用 MCP 检查器

构建 MCP 服务器

逐步了解从头构建服务器

连接本地服务器

完整的 claude_desktop_config.json 参考和故障排除