> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 调试
> 调试模型上下文协议（MCP）集成的综合指南
在开发 MCP 服务器或将其与应用程序集成时，有效的调试至关重要。本指南介绍 MCP 生态系统中可用的调试工具和方法。
## 调试工具概览
MCP 提供了多个不同层级的调试工具：
1. **[MCP Inspector](/docs/2026-07-28/tools/inspector)**：交互式、与传输无关的
测试 UI。可连接到 stdio 或 Streamable HTTP 服务器，调用
[tools](/specification/latest/server/tools)、[prompts](/specification/latest/server/prompts) 和
[resources](/specification/latest/server/resources)，并查看
通知流。这应该是你的首选工具。
2. **服务器日志记录**：以结构化日志形式输出到 stderr（stdio 传输）或通过
[OpenTelemetry](https://opentelemetry.io/)（所有传输方式）。
协议中的 [Logging](/specification/2026-07-28/server/utilities/logging)
（`notifications/message`）自协议版本 `2026-07-28` 起已弃用。
3. **客户端开发者工具**：大多数 MCP 客户端都会公开日志和连接
状态。下面的 [在 Claude Desktop 中调试](#debugging-in-claude-desktop)
是一个示例，或者查阅你所用客户端的文档。
## 实现日志记录
### 服务器端日志记录
当构建使用本地
[stdio 传输](/specification/2026-07-28/basic/transports/stdio) 的服务器时，所有记录到 stderr（标准错误）的消息都会被宿主应用程序自动捕获。
本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议运行。
对于使用
[Streamable HTTP 传输](/specification/2026-07-28/basic/transports/streamable-http) 的服务器，stderr 不会被客户端捕获。请使用你自己的服务器端日志聚合工具或 [OpenTelemetry](https://opentelemetry.io/) 记录日志，并使用标准 HTTP 工具（curl、浏览器 DevTools 的 Network 面板）来检查请求和 SSE 流。
下面的 `notifications/message` 机制自协议版本 `2026-07-28` 起已被弃用。在弃用窗口期间它仍然可用。
对于所有[传输](/specification/latest/basic/transports)，请记录服务器运行时所执行的操作：
```python Python theme={null}
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."
```
```typescript TypeScript theme={null}
await server.sendLoggingMessage({
level: "info",
data: "服务器已成功启动",
});
```
MCP 定义了八个
[RFC 5424 严重性级别](/specification/latest/server/utilities/logging#log-levels)
（`debug` 到 `emergency`）。客户端通过在请求的 `_meta` 中设置
[`io.modelcontextprotocol/logLevel`](/specification/2026-07-28/server/utilities/logging#per-request-log-level)
字段，按请求选择接收日志消息。对于省略此字段的请求，服务器不得发送 `notifications/message`。
应记录的重要事件包括：
* 启动步骤
* 资源访问
* 工具执行
* 错误情况
* 性能指标
## 常见问题
下面的示例使用 Claude Desktop 的
[`claude_desktop_config.json`](/docs/2026-07-28/develop/connect-local-servers)；同样的
原则适用于任何基于 stdio 的 MCP 客户端。
### 工作目录
当 MCP 客户端启动一个 stdio 服务器时：
* 通过客户端配置启动的服务器的工作目录可能是
未定义的（例如在 macOS 上可能是 `/`），因为客户端可能从
任何位置启动
* 在配置和 `.env` 文件中始终使用绝对路径，以确保
稳定运行
* 对于通过命令行直接测试服务器，工作目录将是
你运行命令时所在的位置
例如在 `claude_desktop_config.json` 中，使用：
```json theme={null}
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/data"
]
}
}
}
```
而不是使用像 `./data` 这样的相对路径
### 环境变量
通过 stdio 启动的 MCP 服务器只会自动继承一小部分
环境变量（具体集合取决于平台）。
要覆盖默认变量或提供你自己的变量，可以在
`claude_desktop_config.json` 中指定一个 `env` 键：
```json theme={null}
{
"mcpServers": {
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key"
}
}
}
}
```
### 服务器启动
常见的启动问题：
1. **路径问题**
* 服务器可执行文件路径错误
* 缺少必需文件
* 权限问题
* 尝试为 `command` 使用绝对路径
2. **配置错误**
* 无效的 JSON 语法
* 缺少必需字段
* 类型不匹配
3. **环境问题**
* 缺少环境变量
* 变量值不正确
* 权限限制
### 连接问题
当服务器无法连接时：
1. 检查客户端日志
2. 验证服务器进程是否正在运行
3. 使用 [Inspector](/docs/2026-07-28/tools/inspector) 独立测试
4. 验证
[协议兼容性](/docs/2026-07-28/learn/versioning#negotiation)：调用
[`server/discover`](/specification/2026-07-28/server/discover) 查看
服务器支持哪些协议版本。`UnsupportedProtocolVersionError`
（`-32022`）会在其 `data` 字段中列出服务器支持的
版本
5. 检查
[每个请求的 `_meta` 字段](/specification/2026-07-28/basic/index#meta)：
每个请求都必须携带 `io.modelcontextprotocol/protocolVersion` 和
`io.modelcontextprotocol/clientCapabilities`，客户端也应当包含
`io.modelcontextprotocol/clientInfo`。缺少任一
必需字段的请求都会被以错误 `-32602`（无效参数）拒绝，这与许多其他格式错误输入返回的代码相同。如果服务器需要
请求的 `clientCapabilities` 未声明的某项能力，例如
[elicitation](/specification/2026-07-28/client/elicitation)，它会返回
`MissingRequiredClientCapabilityError`（`-32021`），并指出缺少的
能力。检查请求的 `_meta` 和
[`server/discover`](/specification/2026-07-28/server/discover) 响应，
以验证双方是否声明了你期望的内容
## 在 Claude Desktop 中进行调试
Claude Desktop 是众多 MCP 客户端之一。它可在
macOS 和 Windows 上使用。
### 检查服务器状态
点击聊天输入框中的“Add files, connectors, and more”加号图标，然后
将鼠标悬停在 **Connectors** 菜单上，以查看已连接的服务器和可用工具。
### 查看日志
日志文件写入到：
* macOS: `~/Library/Logs/Claude`
* Windows: `%APPDATA%\Claude\logs`
```bash macOS theme={null}
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```
```powershell Windows theme={null}
type "$env:AppData\Claude\logs\mcp*.log"
```
日志会记录：
* 服务器连接事件
* 配置问题
* 运行时错误
* 消息交换
### 使用 Chrome DevTools
在 Claude Desktop 中访问 Chrome 的开发者工具，以调查
客户端错误：
1. 创建一个 `developer_settings.json` 文件，并将 `allowDevTools` 设置为 true：
```bash macOS theme={null}
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
```
```powershell Windows theme={null}
'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"
```
2. 打开 DevTools：`Command-Option-I`（macOS）或 `Ctrl+Alt+I`（Windows）
注意：你会看到两个 DevTools 窗口：
* 主内容窗口
* 应用标题栏窗口
使用 Console 面板检查客户端错误。
使用 Network 面板检查：
* 消息载荷
* 连接时间
## 调试工作流
### 开发周期
1. 初始开发
* 使用 [Inspector](/docs/2026-07-28/tools/inspector) 进行基本测试
* 实现核心功能
* 添加日志点
2. 集成测试
* 在你的目标 MCP 客户端中进行测试
* 监控日志
* 检查错误处理
### 测试更改
要高效测试更改：
* **配置更改**：重启 MCP 客户端
* **服务器代码更改**：重启客户端（对于 Claude Desktop，请完全退出
然后重新打开；关闭窗口是不够的）
* **快速迭代**：在开发期间使用 [Inspector](/docs/2026-07-28/tools/inspector)
## 最佳实践
### 日志策略
1. **结构化日志**
* 使用一致的格式
* 包含上下文
* 添加时间戳
* 跟踪请求 ID
2. **错误处理**
* 记录堆栈跟踪
* 包含错误上下文
* 跟踪错误模式
* 监控恢复情况
3. **性能跟踪**
* 记录操作耗时
* 监控资源使用情况
* 跟踪消息大小
* 测量延迟
### 安全注意事项
在调试时：
1. **敏感数据**
* 清理日志
* 保护凭据
* 屏蔽个人信息
2. **访问控制**
* 验证权限
* 检查身份验证
* 监控访问模式
有关 MCP 攻击向量和缓解措施的完整说明，请参阅
[安全最佳实践](/docs/2026-07-28/tutorials/security/security_best_practices)。
## 获取帮助
当遇到问题时：
1. **第一步**
* 检查服务器日志
* 使用 [Inspector](/docs/2026-07-28/tools/inspector) 进行测试
* 检查配置
* 验证环境
2. **支持渠道**
* [GitHub issues](https://github.com/modelcontextprotocol/modelcontextprotocol/issues)
* [GitHub discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions)
3. **提供信息**
* 日志摘录
* 配置文件
* 复现步骤
* 环境详情
## 下一步
学习使用 MCP Inspector
从零开始逐步构建一个服务器
claude\_desktop\_config.json 的完整参考与故障排查