> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.transdocs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 调试

> Model Context Protocol (MCP) 集成的完整调试指南

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

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

## 调试工具概览

MCP 提供了多个不同层面的调试工具：

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

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

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

## 在 Claude Desktop 中调试

### 检查服务器状态

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

1. 点击 <img src="https://mintcdn.com/transdocs/yT-0qMgTVh0QCSbv/images/claude-desktop-mcp-plug-icon.svg?fit=max&auto=format&n=yT-0qMgTVh0QCSbv&q=85&s=a30c7d9911474a65574c05acf4b8659d" 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/transdocs/yT-0qMgTVh0QCSbv/images/claude-desktop-mcp-slider.svg?fit=max&auto=format&n=yT-0qMgTVh0QCSbv&q=85&s=78fe6229de6f608cc6867144f32447a5" style={{display: 'inline', margin: 0, height: '1.3em'}} width="24" height="24" data-path="images/claude-desktop-mcp-slider.svg" /> 图标查看：
   * 提供给模型的工具

### 查看日志

从 Claude Desktop 查看详细的 MCP 日志：

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

日志内容包含：

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

### 使用 Chrome DevTools

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

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

```bash theme={null}
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
```

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

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

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

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

使用 Network 面板检查：

* 消息负载
* 连接时间

## 常见问题

### 工作目录

在使用 Claude Desktop 的 MCP 服务器时：

* 通过 `claude_desktop_config.json` 启动的服务器的工作目录可能是未定义的（如 macOS 上的 `/`），因为 Claude Desktop 可能从任何位置启动
* 为确保可靠运行，请在配置和 `.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 Desktop 日志
2. 验证服务器进程是否正在运行
3. 使用 [Inspector](/legacy/tools/inspector) 单独测试
4. 验证协议兼容性

## 实现日志记录

### 服务器端日志

在构建使用本地 stdio [传输](/legacy/concepts/transports) 的服务器时，所有记录到 stderr（标准错误）的消息都会被宿主应用程序（例如 Claude Desktop）自动捕获。

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

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

<CodeGroup>
  ```python Python theme={null}
  server.request_context.session.send_log_message(
    level="info",
    data="服务器已成功启动",
  )
  ```

  ```typescript TypeScript theme={null}
  server.sendLoggingMessage({
    level: "info",
    data: "服务器已成功启动",
  });
  ```
</CodeGroup>

需要记录的重要事件：

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

### 客户端日志

在客户端应用程序中：

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

## 调试工作流程

### 开发周期

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

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

### 测试更改

为了高效测试更改：

* **配置更改**：重启 Claude Desktop
* **服务器代码更改**：使用 Command-R 重新加载
* **快速迭代**：在开发期间使用 [Inspector](/legacy/tools/inspector)

## 最佳实践

### 日志策略

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

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

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

### 安全注意事项

在调试时：

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

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

## 获取帮助

遇到问题时：

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

2. **支持渠道**
   * GitHub issues
   * GitHub discussions

3. **提供信息**
   * 日志片段
   * 配置文件
   * 复现步骤
   * 环境详情

## 下一步

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