调试

​

调试工具概览

1. MCP Inspector：交互式、与传输无关的 测试 UI。可连接到 stdio 或 Streamable HTTP 服务器，调用 tools、prompts 和 resources，并查看 通知流。这应该是你的首选工具。
2. 服务器日志记录：以结构化日志形式输出到 stderr（stdio 传输）或通过 OpenTelemetry（所有传输方式）。 协议中的 Logging （notifications/message）自协议版本 2026-07-28 起已弃用。
3. 客户端开发者工具：大多数 MCP 客户端都会公开日志和连接 状态。下面的 在 Claude Desktop 中调试 是一个示例，或者查阅你所用客户端的文档。

​

实现日志记录

​

服务器端日志记录

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("reports")


@mcp.tool()
async def fetch_report(report_id: str) -> str:
    """按 id 获取报告。"""
    logger.info("正在获取报告 %s", report_id)
    return f"Report {report_id} is ready."

await server.sendLoggingMessage({
  level: "info",
  data: "服务器已成功启动",
});

• 启动步骤
• 资源访问
• 工具执行
• 错误情况
• 性能指标

​

常见问题

​

工作目录

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

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

​

环境变量

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

​

服务器启动

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

​

连接问题

1. 检查客户端日志
2. 验证服务器进程是否正在运行
3. 使用 Inspector 独立测试
4. 验证 协议兼容性：调用 server/discover 查看 服务器支持哪些协议版本。UnsupportedProtocolVersionError （-32022）会在其 data 字段中列出服务器支持的 版本
5. 检查 每个请求的 _meta 字段： 每个请求都必须携带 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities，客户端也应当包含 io.modelcontextprotocol/clientInfo。缺少任一 必需字段的请求都会被以错误 -32602（无效参数）拒绝，这与许多其他格式错误输入返回的代码相同。如果服务器需要 请求的 clientCapabilities 未声明的某项能力，例如 elicitation，它会返回 MissingRequiredClientCapabilityError（-32021），并指出缺少的 能力。检查请求的 _meta 和 server/discover 响应， 以验证双方是否声明了你期望的内容

​

在 Claude Desktop 中进行调试

​

检查服务器状态

​

查看日志

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

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

type "$env:AppData\Claude\logs\mcp*.log"

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

​

使用 Chrome DevTools

1. 创建一个 developer_settings.json 文件，并将 allowDevTools 设置为 true：

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

'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"

2. 打开 DevTools：Command-Option-I（macOS）或 Ctrl+Alt+I（Windows）

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

• 消息载荷
• 连接时间

​

调试工作流

​

开发周期

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

​

测试更改

• 配置更改：重启 MCP 客户端
• 服务器代码更改：重启客户端（对于 Claude Desktop，请完全退出 然后重新打开；关闭窗口是不够的）
• 快速迭代：在开发期间使用 Inspector

​

最佳实践

​

日志策略

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

​

安全注意事项

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

​

获取帮助

1. 第一步
   • 检查服务器日志
   • 使用 Inspector 进行测试
   • 检查配置
   • 验证环境
2. 支持渠道
   • GitHub issues
   • GitHub discussions
3. 提供信息
   • 日志摘录
   • 配置文件
   • 复现步骤
   • 环境详情

​

下一步