【Bug已解决】Claude mcp connection failed / MCP server not responding — Claude MCP 连接失败解决方案 【Bug已解决】Claude: mcp connection failed / MCP server not responding — Claude MCP 连接失败解决方案1. 问题描述Claude Code 无法连接 MCPModel Context Protocol服务器# MCP 连接失败 $ claude 使用 github 工具 Error: MCP connection failed Failed to connect to MCP server github. # 或 MCP 服务器不响应 $ claude Error: MCP server filesystem not responding Server did not respond within 30000ms. # 或 MCP 服务器启动失败 $ claude Error: Failed to start MCP server github Process exited with code 1. # 或 MCP 工具不可用 $ claude 使用数据库工具 Error: MCP tool query not available No MCP server provides this tool.这个问题在以下场景中特别常见MCP 服务器配置错误MCP 服务器进程崩溃网络连接问题MCP 服务器超时依赖缺失端口冲突2. 原因分析原因分类表原因分类具体表现占比配置错误mcp.json约 30%进程崩溃exit code 1约 25%超时30s 不响应约 20%依赖缺失npm 包约 10%网络问题连接失败约 10%端口冲突端口占用约 5%3. 解决方案方案一检查 MCP 配置最推荐# 步骤 1检查 MCP 配置 cat ~/.claude/mcp.json # 或 cat .claude/mcp.json # 步骤 2验证配置格式 python3 -m json.tool .claude/mcp.json # 步骤 3确保 command 和 args 正确 # 例如: { mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ghp_xxx } } } } # 步骤 4验证 claude --debug 21 | grep -i mcp方案二手动启动测试 MCP 服务器# 步骤 1手动启动 npx -y modelcontextprotocol/server-filesystem /tmp # 步骤 2如果报错修复 # 常见: 依赖缺失、Node.js 版本低 # 步骤 3检查 Node.js 版本 node --version # 需要 18 # 步骤 4安装依赖 npm install -g modelcontextprotocol/server-github方案三增加 MCP 超时# 步骤 1设置 MCP 超时 export CLAUDE_MCP_TIMEOUT60000 # 60 秒 claude 使用 github 工具 # 步骤 2或在配置中 cat .claude/settings.json EOF { mcpTimeout: 60000, mcpRetryCount: 3 } EOF # 步骤 3永久设置 echo export CLAUDE_MCP_TIMEOUT60000 ~/.zshrc source ~/.zshrc # 步骤 4验证 claude --debug 21 | grep -i mcp\|timeout方案四配置自动重试# 步骤 1在配置中设置重试 cat .claude/settings.json EOF { mcpRetryCount: 3, mcpRetryDelay: 5000, mcpTimeout: 60000 } EOF # 步骤 2CI/CD 中重试 for i in 1 2 3; do output$(claude --print 使用工具 --max-turns 5 21) if echo $output | grep -qi mcp.*fail\|not respond; then echo MCP failed, retry $i... sleep 5 else echo $output break fi done # 步骤 3验证 claude --debug 21 | grep -i mcp方案五检查网络和端口# 步骤 1检查网络 ping -c 5 github.com # 步骤 2检查端口冲突如果使用 HTTP MCP lsof -i :3000 # 步骤 3检查 DNS nslookup github.com # 步骤 4验证 claude --debug 21 | grep -i network\|connect方案六更新 MCP 服务器# 步骤 1更新 MCP 服务器包 npm update -g modelcontextprotocol/server-github npm update -g modelcontextprotocol/server-filesystem # 步骤 2更新 Claude Code npm update -g anthropic-ai/claude-code # 步骤 3检查 Node.js 版本 node --version # 18 # 步骤 4验证 claude --debug 21 | grep -i mcp claude 使用 github 工具4. 各方案对比总结方案适用场景推荐指数难度方案一检查配置配置⭐⭐⭐⭐⭐低方案二手动启动进程⭐⭐⭐⭐⭐低方案三增加超时超时⭐⭐⭐⭐⭐低方案四自动重试自动化⭐⭐⭐⭐⭐低方案五网络端口网络⭐⭐⭐⭐低方案六更新版本⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 MCP 是什么Model Context Protocol允许 Claude 连接外部工具服务器如 GitHub、文件系统等。5.2 MCP 配置在哪里项目级:.claude/mcp.json用户级:~/.claude/mcp.json5.3 MCP 超时默认多少通常 30 秒。通过CLAUDE_MCP_TIMEOUT调整。5.4 如何手动测试 MCPnpx -y modelcontextprotocol/server-github5.5 MCP 服务器需要什么Node.js 18对应的 npm 包正确的环境变量。5.6 如何增加重试在 settings.json 中设置mcpRetryCount: 3和mcpRetryDelay: 5000。5.7 端口冲突怎么办lsof -i :3000 # 查看 # 更改 MCP 端口或关闭冲突进程5.8 如何调试 MCPclaude --debug 21 | grep -i mcp5.9 CI/CD 中 MCP 不稳定使用重试脚本 CLAUDE_MCP_TIMEOUT60000。5.10 排查清单速查表□ 1. cat .claude/mcp.json 检查配置 □ 2. python3 -m json.tool 验证格式 □ 3. npx 手动启动测试 □ 4. CLAUDE_MCP_TIMEOUT60000 增加超时 □ 5. mcpRetryCount: 3 自动重试 □ 6. node --version 检查 18 □ 7. npm update 更新 MCP 包 □ 8. ping 检查网络 □ 9. lsof -i 检查端口 □ 10. claude --debug | grep mcp 调试6. 总结根本原因MCP 连接失败最常见原因是配置错误30%和进程崩溃25%最佳实践检查.claude/mcp.json配置使用npx手动启动测试 MCP 服务器增加超时export CLAUDE_MCP_TIMEOUT6000060 秒自动重试配置mcpRetryCount: 3和mcpRetryDelay: 5000最佳实践建议确保 Node.js 18更新 MCP 服务器包CI/CD 中使用重试脚本故障排查流程图flowchart TD A[MCP 连接失败] -- B[检查 mcp.json 配置] B -- C[python3 -m json.tool 验证] C -- D{配置正确?} D --|否| E[修复配置] D --|是| F[手动启动测试] E -- G[claude --debug | grep mcp] F -- H[npx -y server-github] H -- I{启动成功?} I --|否| j[检查依赖] I --|是| K[增加超时] j -- L[npm install node 18] L -- G K -- M[CLAUDE_MCP_TIMEOUT60000] M -- N[mcpRetryCount: 3] N -- G G -- O{MCP 连接?} O --|是| P[✅ 问题解决] O --|否| Q[检查网络] Q -- R[ping github.com] R -- S{网络正常?} S --|否| T[修复网络] S --|是| U[检查端口冲突] T -- G U -- V[lsof -i :3000] V -- W{端口占用?} W --|是| X[关闭冲突进程] W --|否| Y[更新 MCP 包] X -- G Y -- Z[npm update -g server-github] Z -- G G -- AA{成功?} AA --|是| P AA --|否| BB[CI/CD: 重试脚本] BB -- CC[for sleep grep mcp] CC -- P P -- DD[长期: 超时 重试 更新] DD -- EE[✅ 长期方案]