MCP中文文档
MCP 开发者文档
调试

调试

社区译文；来源： MCP 80041ab0

在开发 MCP 服务器或将其与应用集成时，有效的调试至关重要。本指南介绍 MCP 生态中可用的调试工具与方法。

调试工具概览

MCP 提供多种针对不同层级的调试工具：

  1. MCP Inspector ：交互式、与传输方式无关的测试界面。连接到 stdio 或 Streamable HTTP 服务器，调用工具 、prompt 和资源 ，并观察通知流。这应当是你的第一站。
  2. 服务器日志：写入 stderr 的结构化日志（stdio 传输），或通过 OpenTelemetry 输出（所有传输方式）。通过协议发送的日志 （notifications/message）自协议版本 2026-07-28 起已废弃。
  3. 客户端开发者工具：大多数 MCP 客户端都会暴露日志和连接状态。示例见下方的 Claude Desktop 中的调试 ，或查阅你所使用客户端的文档。

实现日志记录

服务端日志

在构建使用本地 stdio 传输 的服务器时，所有写入 stderr（标准错误）的日志都会被宿主应用自动捕获。

本地 MCP 服务器不应把日志写入 stdout（标准输出），否则会干扰协议运行。

对于使用 Streamable HTTP 传输 的服务器，客户端不会捕获 stderr。请使用你自己的服务端日志聚合方案或 OpenTelemetry 记录日志，并使用标准 HTTP 工具（curl、浏览器 DevTools 的 Network 面板）检查请求和 SSE 流。

下文所述的 notifications/message 机制自协议版本 2026-07-28 起已废弃。在废弃窗口期内它仍然可用。

对于所有传输方式 ，请记录服务器运行期间的行为：

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("reports")


@mcp.tool()
async def fetch_report(report_id: str) -> str:
    """Fetch a report by id."""
    logger.info("Fetching report %s", report_id)
    return f"Report {report_id} is ready."
await server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});

MCP 定义了八种 RFC 5424 严重级别 （从 debug 到 emergency）。客户端通过在请求的 _meta 中设置 io.modelcontextprotocol/logLevel 字段，按请求选择接收日志消息。对于省略该字段的请求，服务器不得发送 notifications/message。

应当记录的重要事件：

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

常见问题

以下示例使用 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. 用 Inspector 独立测试
  4. 验证协议兼容性 ：调用 server/discover 查看服务器支持哪些协议版本。UnsupportedProtocolVersionError（-32022）会在其 data 字段中列出服务器支持的版本
  5. 检查逐请求的 _meta 字段 ：每个请求都必须携带 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities，客户端还应包含 io.modelcontextprotocol/clientInfo。缺少任一必填字段的请求会以错误 -32602（Invalid params）被拒绝——许多其他格式错误的输入也返回同一错误码。如果服务器需要请求的 clientCapabilities 未声明的能力（例如 elicitation ），它会返回 MissingRequiredClientCapabilityError（-32021）并指出缺失的能力。检查请求的 _meta 和 server/discover 响应，以确认双方声明的正是你所期望的内容

Claude Desktop 中的调试

Claude Desktop 是众多 MCP 客户端之一。它支持 macOS、Windows 和 Linux。

检查服务器状态

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

可用的 MCP 工具

查看日志

日志文件写入：

  • 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

在 Claude Desktop 内部打开 Chrome 的开发者工具，以排查客户端侧错误：

  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"
  1. 打开 DevTools：Command-Option-I（macOS）或 Ctrl+Alt+I（Windows）

注意：你会看到两个 DevTools 窗口：

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

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

使用 Network 面板检查：

  • 消息负载
  • 连接时序

调试工作流

开发周期

  1. 初始开发

    • 用 Inspector 做基础测试
    • 实现核心功能
    • 添加日志记录点

  2. 集成测试

    • 在你的目标 MCP 客户端中测试
    • 监控日志
    • 检查错误处理

测试变更

为了高效地测试变更：

  • 配置变更：重启 MCP 客户端
  • 服务器代码变更：重启客户端（对 Claude Desktop 而言，要完全退出再重新打开；仅关闭窗口是不够的）
  • 快速迭代：开发期间使用 Inspector

最佳实践

日志策略

  1. 结构化日志

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

  2. 错误处理

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

  3. 性能跟踪

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

安全考虑

调试时：

  1. 敏感数据

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

  2. 访问控制

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

关于 MCP 攻击向量与缓解措施的完整论述，参见安全最佳实践 。

获取帮助

遇到问题时：

  1. 第一步

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

  2. 支持渠道

  3. 提供信息

    • 日志摘录
    • 配置文件
    • 复现步骤
    • 环境详情

后续步骤

MCP Inspector

学习使用 MCP Inspector

构建 MCP 服务器

从头开始逐步构建一个服务器

连接本地服务器

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

搭建MCP服务器构建 MCP 客户端