调试

调试 Model Context Protocol (MCP) 集成的综合指南

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

调试工具概览

MCP 提供了多种用于不同层级调试的工具：

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

实现日志记录

服务端日志

在构建使用本地 stdio 传输的服务端时，所有记录到 stderr（标准错误）的消息都会被宿主应用程序自动捕获。

WARNING

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

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

WARNING

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

对于所有传输方式，记录服务端运行时的行为：

PythonTypeScript

python

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."

typescript

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 中，使用：

json

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

而不是像 ./data 这样的相对路径

环境变量

通过 stdio 启动的 MCP 服务端只会自动继承有限的一部分环境变量（具体集合取决于平台）。

要覆盖默认变量或提供你自己的变量，可以在 claude_desktop_config.json 中指定 env 键：

json

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

服务端启动

常见的启动问题：

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

连接问题

当服务端连接失败时：

检查客户端日志
验证服务端进程正在运行
使用 Inspector 单独测试
验证协议兼容性：调用 server/discover 查看服务端支持哪些协议版本。UnsupportedProtocolVersionError（-32022）会在其 data 字段中列出服务端支持的版本
检查逐请求 _meta 字段：每个请求都必须携带 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities，客户端还应包含 io.modelcontextprotocol/clientInfo。缺少任一必需字段的请求会被拒绝，错误为 -32602（Invalid params），这也是许多其他格式错误输入所返回的同一错误码。如果服务端需要某项能力，而请求的 clientCapabilities 未声明该能力（例如征询），它会返回 MissingRequiredClientCapabilityError（-32021），并指明缺失的能力。检查请求的 _meta 和 server/discover 响应，以验证双方声明的能力符合你的预期

在 Claude Desktop 中调试

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

检查服务端状态

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

查看日志

日志文件写入位置：

macOS：~/Library/Logs/Claude
Windows：%APPDATA%\Claude\logs

macOSWindows

bash

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

powershell

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

日志会记录：

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

使用 Chrome DevTools

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

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

macOSWindows

bash

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

powershell

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

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

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

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

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

使用 Network 面板检查：

消息负载
连接时序

调试工作流

开发周期

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

测试变更

为了高效地测试变更：

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

最佳实践

日志策略

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

安全注意事项

调试时：

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

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

获取帮助

遇到问题时：

首要步骤
- 检查服务端日志
- 使用 Inspector 进行测试
- 检查配置
- 验证环境
支持渠道
- GitHub issues
- GitHub discussions
提供信息
- 日志摘录
- 配置文件
- 复现步骤
- 环境详情

后续步骤

MCP Inspector

学习使用 MCP Inspector

Build an MCP server

从头开始构建一个服务端

Connect local servers

完整的 claude\_desktop\_config.json 参考与故障排除

调试