ORANGE BOOK · MCP

附录 C：故障排查手册

一、安装阶段

症状 1：command not found: npx

  • 原因：Node.js 没装或没加 PATH。
  • 解决：去 nodejs.org 下载 LTS 安装包重装，勾选 Add to PATH。
  • 兜底：用 nvm（Mac/Linux）或 nvm-windows 重装。

症状 2：command not found: uvx

  • 原因：uv 没装。
  • 解决（Mac/Linux）：curl -LsSf https://astral.sh/uv/install.sh | sh
  • 解决（Windows）：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • 兜底：用 pip 全局装对应 MCP 包。

症状 3：npm install 卡住 / 超时

  • 原因：网络问题或 npm registry 慢。
  • 解决（个人电脑）：换源 npm config set registry https://registry.npmmirror.com。
  • 兜底：开 VPN 或挂代理。

症状 4：装的 MCP 包说"not found"

  • 原因：包名拼错 / 包尚未发布到 npm / 用了过期的包名。
  • 解决：去 npmjs.com 搜确认包名。
  • 兜底：去 GitHub 仓库看 README 里"安装"那一段。

二、配置阶段

症状 5：改了 claude_desktop_config.json，Claude 没反应

  • 原因 A：没完全退出 Claude（最常见！）。Cmd+Q 或托盘 → Exit。
  • 原因 B：JSON 语法错。去 jsonlint.com 校验。
  • 原因 C：路径不存在。args 里写的目录必须真实存在。

症状 6：工具图标出现，但点开是空的

  • 原因：MCP 服务器启动失败但 Claude 没明显报错。
  • 解决：看日志：
    • Mac：~/Library/Logs/Claude/
    • Windows：%APPDATA%\Claude\logs\
  • 找到 mcp-server-xxx.log，看最后几行。

症状 7：日志里看到 EACCES 或 permission denied

  • 原因：对某个文件 / 目录 / 端口没有权限。
  • 解决：
    • 文件：chmod/管理员权限；
    • 端口：换个端口；
    • 远程 API：检查 token 权限。

症状 8：日志里看到 ENOENT: no such file or directory

  • 原因：args 里的目录或文件路径不存在。
  • 解决：检查路径，建议先 ls /your/path 确认。

症状 9：Windows 路径写反斜杠报错

  • 解决：双反斜杠 C:\\Users\\you\\Desktop 或正斜杠 C:/Users/you/Desktop。

症状 10：JSON 改完启动一直崩

  • 解决步骤：
    1. 把 JSON 替换成最简版（只留一个 filesystem）；
    2. 启动 Claude 验证；
    3. 一个一个加回去；
    4. 加到哪个崩了，说明它有问题。

三、运行阶段

症状 11：AI 不主动调 MCP

  • 原因：提示词不够明确，AI 不知道要用工具。
  • 解决：提示词里显式提到工具名："请用 brave-search……"。

症状 12：AI 调用工具时弹"Authorization required"

  • 原因：远程 MCP 的 OAuth token 失效。
  • 解决：在客户端里重新走一次 OAuth 授权。

症状 13：AI 调用工具返回 401 Unauthorized

  • 原因：API Key 错或过期。
  • 解决：去对应平台重新生成 token / API key 替换。

症状 14：AI 调用工具返回 403 Forbidden

  • 原因：token / OAuth scope 不够。
  • 解决：去 OAuth 授权页加权限，或重新申请 token。

症状 15：AI 调用工具返回 429 Too Many Requests

  • 原因：API 调用次数超限。
  • 解决：等额度恢复 / 升级套餐 / 减少调用频率。

症状 16：AI 一直循环调用同一个工具

  • 原因：模型决策异常或工具响应让它误判。
  • 解决：在提示词里加"如果某工具连续调用 3 次仍未拿到预期结果，就停下来问我"。

症状 17：AI 说调用了工具，但实际没看到调用记录

  • 原因：模型在 hallucinate（幻觉），实际没真调。
  • 解决：在客户端 UI 里看实际调用记录；告诉 AI"必须真实调用 MCP 工具，不要捏造"。

四、远程 MCP 阶段

症状 18：OAuth 授权页打不开 / 卡白屏

  • 原因：浏览器代理 / VPN 干扰。
  • 解决：关掉代理重试 / 换浏览器试。

症状 19：远程 MCP 时不时断连

  • 原因：网络抖动或服务端问题。
  • 解决：
    • 看服务端 status page；
    • 客户端里删除该 MCP 配置 → 重启 → 重新加上；
    • 看日志里有没有 WebSocket closed / EOF 等信息。

症状 20：mcp-remote 跑不起来

  • 原因：端口被占 / token 没传 / 防火墙拦。
  • 解决：换端口 / 检查 --token / 关防火墙再测。

五、性能与体验

症状 21：Claude 启动很慢（10 秒以上）

  • 原因：MCP 太多，每个都启动一次。
  • 解决：把不常用的 MCP 加 _disabled_ 前缀禁用。

症状 22：每次调用 npx 包都重新下载

  • 原因：用的 npx -y package，每次 fetch latest。
  • 解决：全局装一次 npm i -g package，args 改成 package。

症状 23：MCP 占用大量 CPU / 内存

  • 原因：可能进了死循环 / 在大量抓数据 / 服务器实现有 bug。
  • 解决：重启 Claude；如果反复出现，去 GitHub 反馈 bug。

六、安全异常

症状 24：发现 MCP 调了我没要求的工具

  • 立刻做：
    1. 关掉 Claude；
    2. 把可疑 MCP 从配置文件里删掉；
    3. 撤销所有相关 OAuth；
    4. 改密码 + 启用 2FA。

症状 25：账号被通知"异常登录"

  • 解决：
    1. 按平台的"已授权应用"列表，撤销所有可疑 MCP；
    2. rotate token；
    3. 看 MCP 来源，是否官方 / 是否最近升过级 → 上 GitHub 看 changelog。

七、按平台分类的快速参考

Claude Desktop

  • 配置文件：~/Library/Application Support/Claude/claude_desktop_config.json
  • 日志：~/Library/Logs/Claude/
  • 常见命令：完全退出 = Cmd+Q

Cursor

  • 配置在 Settings → Features → MCP
  • 日志：在 Cursor 内查看 Output → MCP Logs
  • 配置文件：~/.cursor/mcp.json（部分版本）

VS Code（Copilot）

  • 配置：~/.vscode/mcp.json 或 .vscode/mcp.json
  • 日志：在 Output 面板选 GitHub Copilot Chat

ChatGPT

  • 配置：Settings → Connectors
  • 取消授权：在 Connector 详情里点 Disconnect
  • 自定义连接器：通过 Apps SDK / mcp-remote

八、终极兜底：万能 5 步法

任何 MCP 问题不知道怎么办，按这五步走：

  1. 完全退出客户端 → 重启；
  2. JSON 用 jsonlint 校验；
  3. 看日志（按对应客户端的位置）；
  4. 去 MCP 服务器 GitHub 看最近 30 天 issue——你大概率不是第一个遇到的人；
  5. 去 github.com/modelcontextprotocol/servers/discussions 提问。