【Bug已解决】Claude Code MCP server connection timeout / ECONNREFUSED — Claude Code MCP Server 连接超时解决方案1. 问题描述Claude Code 启动后无法连接已配置的 MCP Server报出连接超时或拒绝连接错误# 启动 Claude CodeMCP Server 连接超时 $ claude 使用 filesystem 工具读取文件 Error: MCP server filesystem connection timeout Failed to connect to MCP server within 5000ms at MCPClient.connect (~/.claude/mcp/client.js:45:11) at async Promise.all (index 0) # 或连接被拒绝 $ claude Error: MCP server github connection failed ECONNREFUSED 127.0.0.1:3000 Is the MCP server running? # 或 stdio 模式下子进程启动失败 $ claude Error: MCP server sqlite failed to start spawn npx ENOENT Command: npx -y modelcontextprotocol/server-sqlite # 或 MCP Server 启动后立即退出 $ claude Warning: MCP server postgres exited with code 1 Error output: Error: Cannot find module pg at require (internal/modules/cjs/loader.js:885) # 或 MCP 工具列表为空 $ claude 列出所有可用的 MCP 工具 Available MCP tools: (none) # MCP Server 已配置但未提供任何工具有时表现为MCP Server 进程启动后立即崩溃stdio 通信管道断裂MCP Server 响应过慢被 Claude Code 判定为超时配置文件中 server 路径错误MCP Server 依赖缺失导致启动失败多个 MCP Server 同时连接时部分失败这个问题在以下场景中特别常见MCP Server 配置路径错误或不存在MCP Server 依赖的 npm 包未安装stdio 模式下命令执行环境不一致MCP Server 启动时间超过 5 秒超时限制端口被其他进程占用Node.js 版本不满足 MCP Server 要求2. 原因分析核心原理拆解Claude Code 启动 → 读取 mcp config → 连接每个 MCP Server ↓ stdio 模式: spawn 子进程, 通过 stdin/stdout 通信 sse 模式: HTTP 连接到指定 URL ↓ 子进程启动失败 / 端口未监听 / 超时 / 依赖缺失 ↓ MCP Server 连接失败相关工具不可用MCP 通信模式对比stdio 模式: Claude Code → spawn 子进程 (npx/node/python) → stdin/stdout JSON-RPC 适用于: 本地工具 (filesystem, sqlite, github) 常见问题: 命令找不到、依赖缺失、子进程崩溃 SSE 模式: Claude Code → HTTP GET (事件流) POST (请求) → 远程 MCP Server 适用于: 远程服务、Web API 集成 常见问题: 端口未监听、CORS、超时原因分类表原因分类具体表现占比命令/路径错误spawn ENOENT, 找不到命令约 30%依赖缺失Cannot find module, 包未安装约 25%启动超时超过 5 秒未就绪约 15%端口冲突EADDRINUSE, 端口被占约 12%配置错误JSON 格式/字段名错误约 10%子进程崩溃exit code 1, 运行时错误约 8%3. 解决方案方案一验证 MCP Server 命令可执行最推荐# 步骤 1查看 MCP 配置 cat ~/.claude/mcp.json # 或项目级配置 cat .claude/mcp.json # 步骤 2手动执行 MCP Server 命令验证 # 以 filesystem server 为例 npx -y modelcontextprotocol/server-filesystem /tmp # 如果能正常启动并等待输入说明命令可用 # 步骤 3检查 npx 是否可用 which npx which node node --version # MCP Server 通常需要 Node.js 18 # 步骤 4如果 npx 找不到 npm install -g npx # 或确保 Node.js 安装正确 nvm install 22 nvm use 22 # 步骤 5预先安装 MCP Server 包避免每次 npx 下载 npm install -g modelcontextprotocol/server-filesystem # 配置中使用全局安装的命令方案二修复 MCP 配置文件# 步骤 1检查配置文件语法 python3 -m json.tool ~/.claude/mcp.json # 确保无语法错误 # 步骤 2标准配置格式 cat ~/.claude/mcp.json EOF { mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/zhubo/projects], env: { NODE_PATH: /usr/local/lib/node_modules } }, sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db-path, /tmp/data.db] } } } EOF # 步骤 3使用绝对路径避免 PATH 问题 # 查找 npx 绝对路径 which npx # /Users/zhubo/.nvm/versions/node/v22.0.0/bin/npx cat ~/.claude/mcp.json EOF { mcpServers: { filesystem: { command: /Users/zhubo/.nvm/versions/node/v22.0.0/bin/npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] } } } EOF # 步骤 4验证配置加载 claude --debug 21 | grep -i mcp # 应显示 MCP servers loaded: filesystem, sqlite方案三增加连接超时时间# 步骤 1在 mcp.json 中设置超时 cat ~/.claude/mcp.json EOF { mcpServers: { postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], timeout: 15000 } }, defaults: { connectionTimeout: 15000, requestTimeout: 30000 } } EOF # 步骤 2或通过环境变量设置 export CLAUDE_MCP_TIMEOUT15000 export CLAUDE_MCP_REQUEST_TIMEOUT30000 # 步骤 3永久设置 cat ~/.zshrc EOF export CLAUDE_MCP_TIMEOUT15000 EOF source ~/.zshrc # 步骤 4对于启动慢的 MCP Server如需要下载依赖 # 预先安装依赖 npm install -g modelcontextprotocol/server-postgres npm install -g pg # 步骤 5重启 Claude Code claude方案四修复 SSE 模式端口冲突# 步骤 1检查端口是否被占用 lsof -i :3000 # 如果有其他进程占用更换端口 # 步骤 2在 mcp.json 中配置 SSE 模式 cat ~/.claude/mcp.json EOF { mcpServers: { remote-api: { transport: sse, url: http://127.0.0.1:3100/sse } } } EOF # 步骤 3确保 MCP Server 正在监听 # 先启动 MCP Server npx -y modelcontextprotocol/server-filesystem --port 3100 # 然后启动 Claude Code claude # 步骤 4测试连通性 curl http://127.0.0.1:3100/sse --max-time 5 # 应返回 SSE 事件流 # 步骤 5如果端口被占用杀掉旧进程 kill $(lsof -t -i :3100) claude方案五安装缺失依赖# 步骤 1手动运行 MCP Server 查看报错 npx -y modelcontextprotocol/server-sqlite --db-path /tmp/test.db # 如果报 Cannot find module安装对应依赖 # 步骤 2常见 MCP Server 依赖 npm install -g modelcontextprotocol/server-filesystem npm install -g modelcontextprotocol/server-sqlite npm install -g modelcontextprotocol/server-postgres npm install -g modelcontextprotocol/server-github # 步骤 3Python MCP Server 依赖 pip install mcp pip install psycopg2-binary # postgres # 步骤 4检查 Node.js 版本兼容性 node -e console.log(process.version) # 某些 MCP Server 需要 Node.js 20 # 步骤 5验证 MCP Server 能独立运行 echo {jsonrpc:2.0,method:initialize,params:{},id:1} | \ npx -y modelcontextprotocol/server-filesystem /tmp # 应返回 JSON-RPC 响应方案六调试 MCP Server 启动# 步骤 1启用 MCP 调试日志 export CLAUDE_MCP_DEBUGtrue claude --debug 21 | grep -i mcp # 步骤 2查看 MCP Server stderr 输出 # stdio 模式下 stderr 会被 Claude Code 捕获 claude --debug 21 | tee /tmp/claude-debug.log grep -i mcp\|spawn\|exit /tmp/claude-debug.log # 步骤 3手动测试 stdio 通信 echo {jsonrpc:2.0,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}},id:1} | \ npx -y modelcontextprotocol/server-filesystem /tmp 2/tmp/mcp-stderr.log cat /tmp/mcp-stderr.log # 查看 stderr 中的错误信息 # 步骤 4检查 MCP Server 版本 npx -y modelcontextprotocol/server-filesystem --version # 确保版本与 Claude Code 兼容 # 步骤 5清理 npx 缓存重试 rm -rf ~/.npm/_npx npx -y modelcontextprotocol/server-filesystem /tmp4. 各方案对比总结方案适用场景推荐指数难度方案一验证命令spawn ENOENT⭐⭐⭐⭐⭐低方案二修复配置配置错误⭐⭐⭐⭐⭐低方案三增加超时启动慢⭐⭐⭐⭐低方案四修复端口SSE 模式⭐⭐⭐⭐中方案五安装依赖模块缺失⭐⭐⭐⭐⭐低方案六调试日志复杂问题⭐⭐⭐⭐中5. 常见问题 FAQ5.1 MCP Server 的 stdio 和 SSE 模式有什么区别stdioClaude Code 启动子进程通过标准输入/输出通信。适用于本地工具无需端口SSEClaude Code 通过 HTTP 连接远程 MCP Server。适用于远程服务需要端口两种模式的配置字段不同stdio 用commandargsSSE 用url5.2 为什么 npx 每次都很慢# npx 首次运行时会下载包可能超过 5 秒超时 # 解决方案预先全局安装 npm install -g modelcontextprotocol/server-filesystem # 配置中使用 node 直接运行全局安装的包 which modelcontextprotocol/server-filesystem # 或查找实际入口 ls $(npm root -g)/modelcontextprotocol/server-filesystem/dist/index.js5.3 如何查看哪些 MCP Server 配置了但未连接# 启动时查看 MCP 连接状态 claude --debug 21 | grep -E mcp|MCP # 输出示例 # [DEBUG] MCP server filesystem: connected ✓ # [DEBUG] MCP server github: connection failed ✗ (timeout) # [DEBUG] MCP server sqlite: connected ✓ # 在 Claude Code 中查看可用工具 claude /mcp # 列出所有 MCP Server 状态5.4 MCP Server 启动后立即退出怎么办# 手动运行查看退出原因 npx -y modelcontextprotocol/server-sqlite --db-path /tmp/test.db 21 # 常见原因 # 1. 依赖缺失 → npm install -g package # 2. 参数错误 → 检查 args 配置 # 3. 权限不足 → chmod 修复文件权限 # 4. 数据库文件不存在 → 创建文件5.5 多个 MCP Server 部分失败怎么办# Claude Code 会并行连接所有 MCP Server # 一个失败不影响其他 Server # 查看每个 Server 的状态 claude --debug 21 | grep MCP # 禁用失败的 Server 临时使用 cat ~/.claude/mcp.json EOF { mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp] }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], disabled: true } } } EOF5.6 MCP Server 需要环境变量怎么配置{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ghp_xxxxxxxxxxxx, NODE_PATH: /usr/local/lib/node_modules } } } }5.7 如何测试 MCP Server 是否正常工作# 发送 initialize 请求 echo {jsonrpc:2.0,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}},id:1} | \ npx -y modelcontextprotocol/server-filesystem /tmp # 应返回类似 # {jsonrpc:2.0,result:{protocolVersion:2024-11-05,...},id:1} # 发送 tools/list 请求 echo {jsonrpc:2.0,method:tools/list,params:{},id:2} | \ npx -y modelcontextprotocol/server-filesystem /tmp5.8 Docker 中 MCP Server 连不上# Docker 中需要确保 MCP Server 也在容器内运行 # 或通过 host.docker.internal 连接宿主机的 MCP Server # 方案 1容器内运行 MCP Server docker run -v $(pwd):/workspace node:22 sh -c npm install -g modelcontextprotocol/server-filesystem claude # 方案 2连接宿主机 SSE Server # mcp.json 中使用 host.docker.internal { mcpServers: { remote: { transport: sse, url: http://host.docker.internal:3100/sse } } }5.9 MCP Server 版本不兼容怎么办# 查看 MCP 协议版本 echo {jsonrpc:2.0,method:initialize,params:{},id:1} | \ npx -y modelcontextprotocol/server-filesystem /tmp | jq .result.protocolVersion # 如果版本不兼容安装指定版本 npm install -g modelcontextprotocol/server-filesystem0.4.0 # 或更新 Claude Code 到最新版 npm update -g anthropic-ai/claude-code5.10 排查清单速查表□ 1. cat ~/.claude/mcp.json 检查配置语法 □ 2. which npx/node 确认命令可用 □ 3. 手动运行 MCP Server 命令验证 □ 4. npm install -g 安装缺失的 MCP 包 □ 5. timeout 设为 15000 增加超时 □ 6. 使用绝对路径代替 npx □ 7. lsof -i 检查 SSE 端口是否占用 □ 8. --debug 查看 MCP 连接日志 □ 9. echo JSON-RPC 测试 stdio 通信 □ 10. disabled: true 临时禁用失败的 Server6. 总结根本原因MCP Server 连接失败最常见原因是命令/路径错误30%spawn ENOENT和依赖缺失25%Cannot find module最佳实践预先npm install -g安装 MCP Server 包配置中使用which npx获取的绝对路径超时调整启动慢的 MCP Server 在mcp.json中设置timeout: 15000或通过CLAUDE_MCP_TIMEOUT环境变量调试方法手动执行 MCP Server 命令查看 stderr通过echo JSON-RPC | npx测试 stdio 通信最佳实践建议用claude --debug 21 | grep mcp查看每个 Server 连接状态失败的 Server 设置disabled: true临时跳过逐一修复故障排查流程图flowchart TD A[MCP Server 连接失败] -- B[手动运行 MCP Server 命令] B -- C{命令可执行?} C --|否, ENOENT| D[which npx 检查路径] D -- E[使用绝对路径或安装 npx] E -- F[更新 mcp.json 配置] C --|是| G{启动成功?} G --|否, 依赖缺失| H[npm install -g 安装依赖] H -- I[重新运行验证] G --|是| J{Claude Code 能连接?} J --|否, 超时| K[增加 timeout 到 15000] K -- L[CLAUDE_MCP_TIMEOUT 环境变量] L -- M[重启 claude] J --|否, 端口冲突| N[lsof -i 检查端口] N -- O[kill 占用端口的进程] O -- M J --|是| P{工具列表非空?} P --|是| Q[✅ 问题解决] P --|否| R[发送 tools/list JSON-RPC 测试] R -- S[检查 MCP 协议版本兼容性] S -- T[更新 MCP Server 或 Claude Code] T -- M M -- U{是否稳定?} U --|是| Q U --|否| V[启用 --debug 调试日志] V -- W[grep mcp 查看连接详情] W -- X[逐个禁用排查] X -- Q