【Bug已解决】MCP error -32000: Connection closed — Claude Code MCP 连接断开解决方案

【Bug已解决】MCP error -32000: Connection closed — Claude Code MCP 连接断开解决方案1. 问题描述在 Claude Code 中配置 MCPModel Context Protocol服务器后启动会话或调用 MCP 工具时终端弹出以下报错信息MCP error -32000: Connection closed完整的报错可能出现在多种场景中# 场景 1启动 Claude Code 时 $ claude Initializing MCP servers... MCP error -32000: Connection closed (server: playwright) # 场景 2调用 MCP 工具时 使用 playwright 打开浏览器并截图 MCP error -32000: Connection closed # 场景 3长时间会话后 继续使用 MCP 工具 MCP error -32000: Connection closed (server: context7)这个问题在以下场景中特别常见Windows 系统上首次配置 MCP 服务器使用 Playwright、Context7、Sequential-thinking 等热门 MCP ServerMCP Server 通过 npx 启动而非直接二进制启动长时间运行的 Claude Code 会话中调用 MCP 工具企业网络环境下 MCP Server 需要下载额外依赖许多开发者反映MCP 配置看起来完全正确JSON 格式也没有问题但就是反复报Connection closed。在 GitHub Issues 中这是 Claude Code MCP 相关问题中被报告最多的错误。# 典型复现过程 $ claude mcp add-json playwright {command:npx,args:[executeautomation/playwright-mcp-server]} Added MCP server playwright $ claude MCP error -32000: Connection closed (server: playwright) # 反复重试 $ claude --no-mcp # 禁用 MCP 后正常 # 说明问题出在 MCP 配置2. 原因分析核心原理拆解Claude Code 启动 → 通过 stdio 连接 MCP Server ↓ MCP Server 进程启动失败或中途崩溃 ↓ stdio 连接断开 ↓ Claude Code 报 MCP error -32000: Connection closed原因分类表原因分类具体表现占比Windows 上 npx 调用方式错误未通过 cmd /c 包装 npx 命令约 40%MCP Server 依赖未安装npx 首次运行需下载依赖超时或失败约 25%MCP Server 进程崩溃Server 内部错误导致进程退出约 15%超时未完成初始化MCP Server 启动慢超过默认超时约 10%Node.js 版本不兼容MCP Server 需要更高版本 Node.js约 5%配置 JSON 格式错误command/args 字段配置不当约 5%深入说明MCPModel Context Protocol使用 stdio标准输入输出作为默认传输方式。Claude Code 启动时会 fork 一个子进程来运行 MCP Server通过子进程的 stdin/stdout 进行 JSON-RPC 通信。如果子进程启动失败、崩溃或超时Claude Code 就会收到Connection closed错误。Windows 上 npx 调用方式错误是最常见的原因占比高达 40%。在 Windows 上直接使用command: npx往往无法正确启动 MCP Server。这是因为 Windows 的 npm/npx 是一个.cmd脚本而非直接的可执行文件需要通过cmd /c来调用。正确的配置方式是{ command: cmd, args: [/c, npx, -y, executeautomation/playwright-mcp-server] }MCP Server 依赖未安装是第二大原因。当使用npx启动 MCP Server 时如果该包尚未安装在本地npx 会尝试下载。如果网络不稳定或下载超时MCP Server 进程就会启动失败。此外某些 MCP Server如 Playwright还需要额外安装浏览器二进制文件npx playwright install如果浏览器未安装MCP Server 启动后立即崩溃。3. 解决方案方案一Windows 上使用 cmd /c 包装 npx 命令最推荐Windows 用户必须通过cmd /c来调用 npx否则 MCP Server 无法正确启动。# 步骤 1移除旧的错误配置 claude mcp remove playwright -s local # 步骤 2使用正确的配置方式添加 claude mcp add-json playwright {\command\:\cmd\,\args\:[\/c\,\npx\,\-y\,\executeautomation/playwright-mcp-server\]} -s local # 步骤 3验证配置 claude mcp list # 应该看到 playwright 服务器 # 步骤 4启动 Claude Code 测试 claude # 如果不再报 Connection closed说明修复成功对于其他 MCP Server通用配置模板{ mcpServers: { context7: { command: cmd, args: [/c, npx, -y, upstash/context7-mcplatest] }, sequential-thinking: { command: cmd, args: [/c, npx, -y, modelcontextprotocol/server-sequential-thinking] }, playwright: { command: cmd, args: [/c, npx, -y, executeautomation/playwright-mcp-server] } } }方案二预先安装 MCP Server 依赖不要依赖 npx 自动下载提前全局安装 MCP Server 和相关依赖。# 步骤 1全局安装 MCP Server npm install -g executeautomation/playwright-mcp-server npm install -g playwright/test npm install -g upstash/context7-mcp # 步骤 2安装 Playwright 浏览器如果使用 Playwright MCP npx playwright install # 这会下载 Chromium、Firefox、WebKit 浏览器二进制文件 # 步骤 3使用 node 直接启动而非 npx claude mcp add-json playwright {\command\:\node\,\args\:[\/usr/local/lib/node_modules/executeautomation/playwright-mcp-server/dist/index.js\]} # 步骤 4验证 claude # MCP error 应该消失方案三增加 MCP 启动超时时间如果 MCP Server 启动较慢如需要下载依赖或初始化增加超时时间可以避免 Connection closed。# 步骤 1编辑 Claude Code 配置文件 # 配置文件位置: ~/.claude/settings.json 或项目根目录的 .claude/settings.json # 步骤 2添加 MCP 超时配置 cat ~/.claude/settings.json EOF { mcpServers: { playwright: { command: npx, args: [-y, executeautomation/playwright-mcp-server], timeout: 60000 } } } EOF # 步骤 3Windows 版本 cat ~/.claude/settings.json EOF { mcpServers: { playwright: { command: cmd, args: [/c, npx, -y, executeautomation/playwright-mcp-server], timeout: 60000 } } } EOF方案四使用直接路径替代 npxnpx 每次启动都有开销使用 node 直接启动 MCP Server 更稳定。# 步骤 1找到 MCP Server 的入口文件 # 全局安装后 npm root -g # 输出: /usr/local/lib/node_modules 或 ~/.npm-global/lib/node_modules # 步骤 2找到具体入口文件 ls /usr/local/lib/node_modules/executeautomation/playwright-mcp-server/dist/ # 找到 index.js # 步骤 3配置直接路径 claude mcp add-json playwright {\command\:\node\,\args\:[\/usr/local/lib/node_modules/executeautomation/playwright-mcp-server/dist/index.js\]} # 步骤 4验证 claude方案五手动测试 MCP Server 是否能正常启动在配置到 Claude Code 之前先手动运行 MCP Server 确认它能正常工作。# 步骤 1手动运行 MCP Server npx -y executeautomation/playwright-mcp-server # 步骤 2观察输出 # 如果正常会等待 stdin 输入没有立即退出 # 如果立即退出或报错说明 MCP Server 本身有问题 # 步骤 3发送测试 JSON-RPC 请求 echo {jsonrpc:2.0,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:test,version:1.0}},id:1} | npx -y executeautomation/playwright-mcp-server # 步骤 4如果返回了 JSON 响应说明 MCP Server 正常 # 如果没有响应或报错先修复 MCP Server 本身的问题方案六查看 MCP 详细日志定位问题使用 debug 模式查看 MCP 连接的详细日志。# 步骤 1以 debug 模式启动 claude --debug # 步骤 2查看 MCP 相关日志 # debug 模式会输出 MCP Server 的启动过程、stderr 输出等 # 步骤 3查看 MCP 日志文件 ls ~/.claude/logs/ cat ~/.claude/logs/mcp-*.log # 步骤 4常见日志问题 # ENOENT → 命令路径错误 # EACCES → 权限不足 # timeout → 启动超时 # Module not found → 依赖缺失4. 各方案对比总结方案适用场景推荐指数难度方案一cmd /c 包装Windows 用户⭐⭐⭐⭐⭐低方案二预装依赖所有平台依赖问题⭐⭐⭐⭐⭐低方案三增加超时MCP Server 启动慢⭐⭐⭐⭐低方案四直接路径替代 npx更稳定⭐⭐⭐⭐中方案五手动测试排查 MCP Server 本身⭐⭐⭐中方案六查看日志深度排查⭐⭐⭐⭐中5. 常见问题 FAQ5.1 macOS/Linux 上也报 MCP error -32000macOS/Linux 上通常不会有 Windows 的cmd /c问题但仍可能因为依赖未安装或超时报错。使用方案二预先安装依赖或使用方案三增加超时时间。5.2 MCP Server 启动后立即崩溃检查 MCP Server 的 stderr 输出# 手动运行查看错误 npx -y executeautomation/playwright-mcp-server 21 # 常见崩溃原因: # 1. Node.js 版本过低: node --version (需要 18) # 2. 缺少系统依赖: 如 Playwright 需要浏览器 # 3. 端口冲突: 某些 MCP Server 需要绑定端口5.3 长时间会话后 MCP 突然断开MCP Server 进程可能因为内存泄漏或超时被系统杀死。解决方案定期重启 Claude Code 会话使用/mcp命令查看 MCP Server 状态在 settings.json 中配置restartOnCrash: true5.4 多个 MCP Server 中只有一个报 Connection closed说明是特定 MCP Server 的问题而非全局配置问题。使用方案五逐个手动测试找到问题 Server。5.5 使用 Docker 运行 Claude Code 时 MCP 报错Docker 容器中 npx 可能无法正确下载依赖。在 Dockerfile 中预装FROM node:22-slim RUN npm install -g anthropic-ai/claude-code RUN npm install -g executeautomation/playwright-mcp-server RUN npx playwright install --with-deps5.6 MCP 配置 JSON 格式正确但仍报错JSON 格式正确不代表配置正确。检查command字段是否是有效的可执行文件路径args数组中每个参数是否正确环境变量env字段是否正确配置Windows 上是否使用了cmd /c包装5.7 配置了 MCP 但 Claude Code 中看不到工具如果 MCP Server 启动成功但工具未显示可能是 MCP Server 的tools/list响应有问题。使用/mcp命令查看已连接的 MCP Server 和可用工具。如果没有工具列出说明 MCP Server 的工具注册有问题。5.8 企业网络环境下 MCP Server 无法下载依赖企业网络可能阻止了 npm registry 访问。解决方案配置企业 npm 私有镜像在有网络的机器上预装依赖然后复制到企业机器使用直接路径方式方案四避免 npx 下载5.9 MCP Server 更新后报 Connection closedMCP Server 更新可能引入了不兼容的变更。回退到之前的版本# 查看可用版本 npm view executeautomation/playwright-mcp-server versions # 安装指定版本 npm install -g executeautomation/playwright-mcp-server1.0.05.10 排查清单速查表□ 1. Windows 用户确认使用 cmd /c 包装 npx 命令 □ 2. 手动运行 MCP Server 确认能正常启动 □ 3. 全局安装 MCP Server 依赖: npm install -g □ 4. Playwright 用户运行: npx playwright install □ 5. 检查 Node.js 版本: node --version ( 18) □ 6. 使用 --debug 模式查看 MCP 日志 □ 7. 检查 ~/.claude/settings.json 中 MCP 配置 □ 8. 增加 timeout 配置避免启动超时 □ 9. 使用 node 直接路径替代 npx □ 10. 逐个排查找到问题 MCP Server6. 总结根本原因MCP error -32000 是 MCP Server 进程启动失败或崩溃导致的 stdio 连接断开Windows 上最常见原因是未用cmd /c包装 npx 命令最佳实践Windows 用户配置 MCP 时务必使用command: cmd, args: [/c, npx, ...]格式这是解决 40% 问题的万能钥匙依赖管理不要依赖 npx 自动下载提前全局安装 MCP Server 及其依赖如 Playwright 浏览器使用node直接路径启动更稳定排查方法在配置到 Claude Code 之前先手动运行 MCP Server 确认它能正常启动并响应 JSON-RPC 请求最佳实践建议在.claude/settings.json中为每个 MCP Server 配置timeout字段建议 60000ms避免因启动慢导致的 Connection closed 错误故障排查流程图flowchart TD A[出现 MCP error -32000: Connection closed] -- B{操作系统?} B --|Windows| C[检查是否使用 cmd /c 包装 npx] B --|macOS/Linux| D[手动运行 MCP Server 测试] C -- E{已使用 cmd /c?} E --|否| F[修改配置: commandcmd, args加入 /c npx] E --|是| D F -- G[重新启动 Claude Code 验证] D -- H{MCP Server 能正常启动?} H --|否| I{报什么错?} H --|是| J[检查超时配置] I --|Module not found| K[全局安装依赖: npm install -g] I --|Playwright| L[安装浏览器: npx playwright install] I --|Node version| M[升级 Node.js 到 18] I --|其他错误| N[查看 --debug 日志] K -- O[使用 node 直接路径配置] L -- O M -- O N -- O J -- P{增加 timeout 后正常?} P --|是| Q[✅ 问题解决] P --|否| R[逐个禁用 MCP Server 排查] G -- Q H -- S{增加 timeout 到 60000} S -- Q O -- Q R -- T[找到问题 Server 并更新/移除] T -- Q