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

1. 问题描述

在 Claude Code 中配置 MCP（Model 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 Server
• MCP 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%

深入说明

MCP（Model 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-mcp@latest"]
    },
    "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

# 步骤 3：Windows 版本
cat > ~/.claude/settings.json << 'EOF'
{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@executeautomation/playwright-mcp-server"],
      "timeout": 60000
    }
  }
}
EOF

方案四：使用直接路径替代 npx

npx 每次启动都有开销，使用 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. 常见问题 FAQ

5.1 macOS/Linux 上也报 MCP error -32000

macOS/Linux 上通常不会有 Windows 的 cmd /c 问题，但仍可能因为依赖未安装或超时报错。使用方案二预先安装依赖，或使用方案三增加超时时间。

5.2 MCP Server 启动后立即崩溃

检查 MCP Server 的 stderr 输出：

# 手动运行查看错误
npx -y @executeautomation/playwright-mcp-server 2>&1

# 常见崩溃原因:
# 1. Node.js 版本过低: node --version (需要 >= 18)
# 2. 缺少系统依赖: 如 Playwright 需要浏览器
# 3. 端口冲突: 某些 MCP Server 需要绑定端口

5.3 长时间会话后 MCP 突然断开

MCP Server 进程可能因为内存泄漏或超时被系统杀死。解决方案：

• 定期重启 Claude Code 会话
• 使用 /mcp 命令查看 MCP Server 状态
• 在 settings.json 中配置 restartOnCrash: true

5.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-deps

5.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 closed

MCP Server 更新可能引入了不兼容的变更。回退到之前的版本：

# 查看可用版本
npm view @executeautomation/playwright-mcp-server versions

# 安装指定版本
npm install -g @executeautomation/playwright-mcp-server@1.0.0

5.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 Server

6. 总结

1. 根本原因：MCP error -32000 是 MCP Server 进程启动失败或崩溃导致的 stdio 连接断开，Windows 上最常见原因是未用 cmd /c 包装 npx 命令
2. 最佳实践：Windows 用户配置 MCP 时务必使用 "command": "cmd", "args": ["/c", "npx", ...] 格式，这是解决 40% 问题的万能钥匙
3. 依赖管理：不要依赖 npx 自动下载，提前全局安装 MCP Server 及其依赖（如 Playwright 浏览器），使用 node 直接路径启动更稳定
4. 排查方法：在配置到 Claude Code 之前，先手动运行 MCP Server 确认它能正常启动并响应 JSON-RPC 请求
5. 最佳实践建议：在 .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[修改配置: command=cmd, 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