调试 MCP 连接与常见配置错误
High Contrast
Dark Mode
Light Mode
Sepia
Forest
3 min read532 words

调试 MCP 连接与常见配置错误

MCP 配置时最大的挫败感来自于"明明配置好了，工具就是不出现"。本节提供系统性的排错方法和最常见的 20+ 种错误场景，让你快速定位并修复问题。

调试的第一步：查看 MCP 日志

Claude Desktop 和 Cline 都会把 MCP Server 的启动日志写到本地文件：

macOS（Claude Desktop）：

# 实时查看 MCP 日志
tail -f ~/Library/Logs/Claude/mcp*.log
# 查看所有 MCP 相关日志文件
ls ~/Library/Logs/Claude/

Windows（Claude Desktop）：

Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait

Cline（VS Code）：

打开 VS Code 输出面板（Cmd+Shift+U）→ 下拉选择 "Cline" → 查看 MCP 相关输出。

调试流程图

flowchart TD A[工具未出现] --> B{检查 JSON 格式} B -- 语法错误 --> C[用 jsonlint.com 修复] B -- 格式正确 --> D{查看 MCP 日志} D -- 启动失败 --> E{错误类型} D -- 启动成功 --> F{工具列表为空} E -- command not found --> G[检查 npx/node 安装
或使用完整路径] E -- ENOENT --> H[检查文件路径是否存在] E -- EACCES --> I[检查文件/目录权限] E -- 端口占用 --> J[换一个端口或关闭冲突进程] F -- 是 --> K[重新安装 Server npm 包] F -- 否 --> L[重启 Claude Desktop
并等待 10 秒] style C fill:#E74C3C,color:#fff style G fill:#F39C12,color:#fff style L fill:#27AE60,color:#fff

手动测试 MCP Server

在配置到客户端之前，先手动运行 Server 确认它能正常启动：

# 测试 filesystem server 是否能启动
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
npx -y @modelcontextprotocol/server-filesystem /tmp
# 预期输出（截取）：
# {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"read_file",...}]}}

如果这个命令报错，说明是 Server 本身的问题，和 Claude Desktop 无关。

常见错误汇总

错误类型一：JSON 配置格式问题

// ❌ 错误：尾部逗号
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["..."],  // ← 这个逗号不合法
}
}
}
// ✅ 正确
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["..."]
}
}
}

验证 JSON 的快捷命令：

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
# 如果没有输出错误，格式正确

错误类型二：命令路径问题

# 错误现象：Error: spawn npx ENOENT
# 原因：Claude Desktop 启动时的 PATH 与终端不同
# 诊断：找到 npx 的完整路径
which npx
# /usr/local/bin/npx
# 修复：在配置中使用完整路径
{
"command": "/usr/local/bin/npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "..."]
}

错误类型三：权限问题

错误信息 原因 修复
EACCES: permission denied 文件/目录无读权限 chmod +r 对应路径
Error: path not allowed 请求路径在配置目录范围外 添加该路径到 Server 参数
SQLITE_READONLY 数据库文件只读 chmod 644 database.db

错误类型四：环境变量未传递

# 错误：API 密钥未生效
# Error: GITHUB_PERSONAL_ACCESS_TOKEN is not set
# 原因：.bashrc 中的环境变量在 GUI 应用中不一定生效
# 修复方案一：在 config.json 中直接写入（不推荐，有安全风险）
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
# 修复方案二：使用 launchctl（macOS）确保 GUI 应用读取环境变量
launchctl setenv GITHUB_TOKEN "ghp_xxx"
# 需要重启 Claude Desktop 后生效

错误类型五：npx 缓存问题

# 错误：旧版本 Server 残留缓存
# 症状：更新了 Server 版本但行为没有变化
# 清理 npx 缓存
npx clear-npx-cache
# 或者指定版本号强制刷新
"args": ["-y", "@modelcontextprotocol/server-filesystem@latest", "..."]

错误类型六：Server 启动超时

如果 Server 需要较长时间初始化（如下载浏览器），Claude Desktop 可能认为启动失败：

{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"],
"timeout": 30000
}
}
}

MCP Inspector：官方调试工具

Anthropic 提供了一个可视化调试工具，可以在浏览器中测试 MCP Server：

# 安装并启动 Inspector
npx @modelcontextprotocol/inspector \
npx -y @modelcontextprotocol/server-filesystem /tmp
# 打开 http://localhost:5173
# 可以在 UI 中看到工具列表、手动调用工具、查看响应

这是排查"工具定义是否正确"的最直观方式。

本节执行清单

下一章：第 04 章 — 文件与本地环境操作自动化