> ## Documentation Index
> Fetch the complete documentation index at: https://model-context-protocol.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 调试

> 调试模型上下文协议（MCP）集成的综合指南

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

<Info>
  本指南适用于 macOS。其他平台的指南即将推出。
</Info>

## 调试工具概述

MCP 提供了几个不同级别的调试工具：

1. **MCP 检查器**
   * 交互式调试界面
   * 直接服务器测试
   * 详细信息请参阅[检查器指南](/docs/tools/inspector)

2. **Claude 桌面开发者工具**
   * 集成测试
   * 日志收集
   * Chrome DevTools 集成

3. **服务器日志记录**
   * 自定义日志实现
   * 错误跟踪
   * 性能监控

## 在 Claude 桌面版中调试

### 检查服务器状态

Claude.app 界面提供基本的服务器状态信息：

1. 点击 <img src="https://mintcdn.com/model-context-protocol/PuNtBVMoBLtj46Oz/images/claude-desktop-mcp-plug-icon.svg?fit=max&auto=format&n=PuNtBVMoBLtj46Oz&q=85&s=d34e9d1e5176b13035991f6105f24070" style={{display: 'inline', margin: 0, height: '1.3em'}} width="32" height="32" data-path="images/claude-desktop-mcp-plug-icon.svg" /> 图标查看：
   * 已连接的服务器
   * 可用的提示和资源

2. 点击 <img src="https://mintcdn.com/model-context-protocol/PuNtBVMoBLtj46Oz/images/claude-desktop-mcp-hammer-icon.svg?fit=max&auto=format&n=PuNtBVMoBLtj46Oz&q=85&s=42936bf1e7a50a5e612adf929c128b79" style={{display: 'inline', margin: 0, height: '1.3em'}} width="32" height="32" data-path="images/claude-desktop-mcp-hammer-icon.svg" /> 图标查看：
   * 提供给模型的工具

### 查看日志

从 Claude 桌面版查看详细的 MCP 日志：

```bash theme={null}
# 实时跟踪日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```

日志捕获：

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

### 使用 Chrome DevTools

在 Claude 桌面版中访问 Chrome 的开发者工具以调查客户端错误：

1. 启用 DevTools：

```bash theme={null}
jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json
```

2. 打开 DevTools：`Command-Option-Shift-i`

注意：您将看到两个 DevTools 窗口：

* 主内容窗口
* 应用程序标题栏窗口

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

使用 Network 面板检查：

* 消息负载
* 连接时间

## 常见问题

### 工作目录

在 Claude 桌面版中使用 MCP 服务器时：

* 通过 `claude_desktop_config.json` 启动的服务器的工作目录可能未定义（如 macOS 上的 `/`），因为 Claude 桌面版可以从任何地方启动
* 始终在配置和 `.env` 文件中使用绝对路径以确保可靠操作
* 通过命令行直接测试服务器时，工作目录将是您运行命令的地方

例如在 `claude_desktop_config.json` 中，使用：

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
```

而不是相对路径如 `./data`

### 环境变量

MCP 服务器仅自动继承一部分环境变量，如 `USER`、`HOME` 和 `PATH`。

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

```json theme={null}
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}
```

### 服务器初始化

常见的初始化问题：

1. **路径问题**
   * 服务器可执行文件路径不正确
   * 缺少必需文件
   * 权限问题
   * 尝试使用 `command` 的绝对路径

2. **配置错误**
   * 无效的 JSON 语法
   * 缺少必需字段
   * 类型不匹配

3. **环境问题**
   * 缺少环境变量
   * 变量值不正确
   * 权限限制

### 连接问题

当服务器无法连接时：

1. 检查 Claude 桌面版日志
2. 验证服务器进程是否正在运行
3. 使用[检查器](/docs/tools/inspector)独立测试
4. 验证协议兼容性

## 实现日志记录

### 服务器端日志记录

在构建使用本地 stdio [传输](/docs/concepts/transports)的服务器时，所有记录到 stderr（标准错误）的消息将自动由主机应用程序（例如 Claude 桌面版）捕获。

<Warning>
  本地 MCP 服务器不应将消息记录到 stdout（标准输出），因为这会干扰协议操作。
</Warning>

对于所有[传输](/docs/concepts/transports)，您还可以通过发送日志消息通知向客户端提供日志记录：

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    server.request_context.session.send_log_message(
      level="info",
      data="Server started successfully",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    server.sendLoggingMessage({
      level: "info",
      data: "Server started successfully",
    });
    ```
  </Tab>
</Tabs>

重要事件记录：

* 初始化步骤
* 资源访问
* 工具执行
* 错误情况
* 性能指标

### 客户端日志记录

在客户端应用程序中：

1. 启用调试日志记录
2. 监控网络流量
3. 跟踪消息交换
4. 记录错误状态

## 调试工作流程

### 开发周期

1. 初始开发
   * 使用[检查器](/docs/tools/inspector)进行基本测试
   * 实现核心功能
   * 添加日志记录点

2. 集成测试
   * 在 Claude 桌面版中测试
   * 监控日志
   * 检查错误处理

### 测试更改

高效测试更改：

* **配置更改**：重启 Claude 桌面版
* **服务器代码更改**：使用 Command-R 重新加载
* **快速迭代**：在开发过程中使用[检查器](/docs/tools/inspector)

## 最佳实践

### 日志记录策略

1. **结构化日志记录**
   * 使用一致的格式
   * 包含上下文
   * 添加时间戳
   * 跟踪请求 ID

2. **错误处理**
   * 记录堆栈跟踪
   * 包含错误上下文
   * 跟踪错误模式
   * 监控恢复

3. **性能跟踪**
   * 记录操作时间
   * 监控资源使用
   * 跟踪消息大小
   * 测量延迟

### 安全考虑

调试时：

1. **敏感数据**
   * 清理日志
   * 保护凭据
   * 掩盖个人信息

2. **访问控制**
   * 验证权限
   * 检查身份验证
   * 监控访问模式

## 获取帮助

遇到问题时：

1. **第一步**
   * 检查服务器日志
   * 使用[检查器](/docs/tools/inspector)测试
   * 查看配置
   * 验证环境

2. **支持渠道**
   * GitHub 问题
   * GitHub 讨论

3. **提供信息**
   * 日志摘录
   * 配置文件
   * 重现步骤
   * 环境详细信息

## 下一步

<CardGroup cols={2}>
  <Card title="MCP 检查器" icon="magnifying-glass" href="/docs/tools/inspector">
    学习使用 MCP 检查器
  </Card>
</CardGroup>