MCP Server Common Error Troubleshooting

本文汇总 MCP Server 配置和使用过程中最常见的错误信息及解决方法。遇到问题时，先ViewClients日志获取具体错误信息。

如何View错误日志

排查问题的第一步是找到日志文件：

错误 1：command not found / 命令找不到

错误信息：spawn npx ENOENT 或 command not found: npx

原因：Clients启动 Server 时找不到指定的命令。

解决方法：

  1. 确认命令已安装：在终端运行 which npx（macOS/Linux）或 where npx（Windows）
  2. 如果使用 nvm/fnm 等版本管理器，在配置中使用完整路径： 
    "command": "/Users/yourname/.nvm/versions/node/v20.0.0/bin/npx"
  3. 对于 uvx，确认已安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh

错误 2：连接超时 / Server 无响应

错误信息：MCP server connection timeout 或 Server 状态一直显示"connecting"

原因：Server 进程启动了但没有正确响应 MCP Protocol握手。

解决方法：

  1. 在终端手动运行 command + args，确认命令本身能正常执行
  2. 检查是否有交互式提示阻塞了启动（npx 缺少 -y 参数）
  3. 确认网络连接正常（某些 Server 启动时Required下载依赖）
  4. 检查是否有防火墙或代理阻止了本地通信

错误 3：JSON 配置解析失败

错误信息：SyntaxError: Unexpected token 或Clients无法读取配置

原因：配置文件不是合法的 JSON 格式。

解决方法：

  1. 检查是否有多余的逗号（最后一个元素后面不能有逗号）
  2. 确认所有键名都用双引号包裹
  3. 使用 JSON 验证工具检查：cat config.json | python -m json.tool
  4. 注意 Windows 路径的反斜杠Required转义为 \\

错误 4：权限不足 / Permission denied

错误信息：EACCES: permission denied

原因：Server 尝试访问没有权限的文件或目录。

解决方法：

  1. 确认 args 中指定的路径存在且当前用户有读取权限
  2. 不要指向系统保护目录（如 /System、C:\Windows）
  3. macOS 上可能Required在"系统设置 > 隐私与安全 > 文件和文件夹"中授权

错误 5：环境变量未设置

错误信息：API key not found 或 Missing required environment variable

原因：Server Required的 API Key 或 Token 未在 env 字段中配置。

解决方法：

  1. View Server 文档确认Required哪些环境变量
  2. 在配置的 env 字段中添加对应的键值对
  3. 确认 Key 值正确且未过期
"env": {
  "GITHUB_TOKEN": "ghp_your_actual_token_here"
}

错误 6：版本不兼容

错误信息：Unsupported protocol version 或功能异常

原因：Clients和 Server 的 MCP Protocol版本不匹配。

解决方法：

  1. 更新Clients到最新版本
  2. 更新 Server 包：删除缓存后重新运行 npx（npx 会自动拉取最新版）
  3. View Server 仓库的 README 确认支持的Protocol版本

通用排查步骤

  1. View日志文件获取具体错误信息
  2. 在终端手动运行 command + args 确认命令可执行
  3. 用 JSON 验证工具检查配置文件格式
  4. 完全重启Clients（不是刷新窗口）
  5. 尝试最简配置（只保留一个 Server）排除冲突

FAQ

重启后问题依旧怎么办？
尝试删除配置文件中的问题 Server，只保留一个已知可用的 Server 测试。如果单个 Server 也不行，可能是Clients版本问题，尝试更新或重装Clients。
日志中没有有用信息怎么办？
在终端手动运行 Server 命令，观察输出。例如：npx -y @modelcontextprotocol/server-filesystem /tmp，看是否有报错。
macOS 上 npx 路径问题怎么彻底解决？
找到 npx 的完整路径（which npx），然后在配置中使用完整路径替代 "npx"。如果使用 nvm，路径通常是 ~/.nvm/versions/node/vXX.X.X/bin/npx。

Related Links