> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp.ximosoft.cn/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 检查器**
   * 交互式调试界面
   * 直接服务器测试
   * 详见[检查器指南](/docs/tools/inspector)

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

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

## 在 Claude Desktop 中调试

### 检查服务器状态

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

1. 点击 <img src="https://mintcdn.com/magent/4wuiZ9JPF_Ha0vV2/images/claude-desktop-mcp-plug-icon.svg?fit=max&auto=format&n=4wuiZ9JPF_Ha0vV2&q=85&s=23a497bd54ff3386fc1a4dcf8f0e41fd" 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/magent/4wuiZ9JPF_Ha0vV2/images/claude-desktop-mcp-hammer-icon.svg?fit=max&auto=format&n=4wuiZ9JPF_Ha0vV2&q=85&s=d8d33a877074c7bc1bc52509cb3e4872" style={{display: 'inline', margin: 0, height: '1.3em'}} width="32" height="32" data-path="images/claude-desktop-mcp-hammer-icon.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 窗口:

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

使用控制台面板检查客户端错误。

使用网络面板检查:

* 消息负载
* 连接时序

## 常见问题

### 工作目录

在使用带有 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. 使用[检查器](/docs/tools/inspector)单独测试
4. 验证协议兼容性

## 实现日志记录

### 服务器端日志记录

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

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

对于所有[传输](/docs/concepts/transports)，你也可以通过发送日志消息通知来向客户端提供日志:

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

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

需要记录的重要事件:

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

### 客户端日志记录

在客户端应用程序中:

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

## 调试工作流

### 开发周期

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

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

### 测试更改

要高效地测试更改:

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

## 最佳实践

### 日志策略

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

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

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

### 安全考虑

在调试时:

1. **敏感数据**
   * 净化日志
   * 保护凭证
   * 屏蔽个人信息

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

## 获取帮助

遇到问题时:

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

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

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

## 下一步

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