Claude MCP server 老是断开：一次性修好

打开 Claude Desktop 或 Claude Code，工具列表里 MCP server 出现了，过一两分钟它就变灰、显示 “disconnected”。点 reconnect 又能连上，几分钟后又掉。这是 Claude MCP（Model Context Protocol）集成的典型故障。截至 2026 年 6 月，根因几乎都落在这几处之一：本地 server 进程崩了、启动超过了 Claude 约 60 秒的初始化窗口、OAuth token 过期、或者配置里的路径 / Node 二进制路径写错了。

最快的修法（覆盖九成情况）：打开日志，找到断开那一行紧接着的内容，对照下面的表。看到 exited with code 1 是 server 崩了；ENOENT / EACCES 是路径或权限问题；启动后约 60 秒出现 Server transport closed 是启动超时；工具调用返回 401 是 token 过期。看一次日志，修一次到位。

开始前先理解一件事：MCP 不是 HTTP 长轮询。对本地（stdio）server 来说，Claude 会启动一个子进程，通过 stdin/stdout 与它通信。stdio server 不会自动重连——子进程一旦死了，工具就一直是死的，直到你重启或手动 reconnect。而 HTTP 和 SSE server 会自动重连（Claude Code 用指数退避重试，最多五次）。所以 stdio 故障和远程故障在界面上看起来一样，修法却不同。

你属于哪一类？

找到断开那一行紧接着的日志，跳到对应的修复步骤。

日志 / 现象	最可能的原因	跳到
exited with code 1、killed 或一段堆栈	server 进程崩 / 被 OOM kill	Step 2 + Step 3
启动后约 60 秒出现 Server transport closed，无报错	启动超过约 60 秒初始化窗口	Step 4
ENOENT: no such file or directory	配置里路径错或用了相对路径	Step 2
EACCES: permission denied	Claude 没有读文件 / 目录的权限	Step 2
工具调用返回 401 / unauthorized	OAuth token 过期且没自动刷新	Step 5
固定每 30s / 60s 掉一次，只对远程 server	企业代理切断了长连接	Step 6
Cannot find module / Unexpected token	Node/Python 版本不匹配	Step 7
每个 server 都在 initialize 之后立即失败	Claude Desktop / 系统级 bug	见 FAQ

常见原因（按命中率从高到低）

1. 本地 stdio server 崩或被 OOM kill

stdio 模式的 MCP server 是 Claude 启动的 Node / Python 子进程。它会因内存超限被 OOM kill、未捕获异常自爆、或在错误的运行时版本下启不来。因为 stdio server 不自动重连，崩一次工具这一整段会话就没了。

如何判断：日志里有 exited with code 1、killed 或一段堆栈。

2. 启动超过约 60 秒的初始化窗口

这是最容易被漏诊的原因。Claude 大约只等 60 秒让 stdio server 完成初始化。那些首次运行要下载重量级依赖的 server 会超时——比如 Puppeteer server 要拉 Chromium（约 180 MB）、Python server 在解析包、或任何 npx 启动的 server 在做冷启动 npm install。日志会在约 60 秒处显示 Server transport closed，但并没有真正的报错。

如何判断：断开发生在启动后约 60 秒；首次运行很慢但后续就正常（或反过来——缓存被清掉后又慢了）；server 是 npx 或容器启动的。

3. 配置里路径错或权限不够

最高频的本地坑。args 里用了相对路径、指向一个不存在的文件、或者放在一个 Claude 没读权限的目录。

如何判断：日志里出现 ENOENT: no such file or directory 或 EACCES: permission denied。

4. OAuth token 过期，server 没刷新

远程 MCP（官方的 Notion、Sentry、GitHub、Asana server）走 OAuth 或 bearer token。token 过期、实现又没自动 refresh 时，连接看着是活的，但每次工具调用都返回 401。

如何判断：工具调用返回 unauthorized / 401；重新走一遍 OAuth 就好。

5. Node / Python 版本不匹配

MCP server 一般要求 Node 18+（2026 年推荐 Node 22 LTS）或 Python 3.10+，但你 PATH 里第一个 node 是旧版——比如系统自带的 Node。Claude 继承 PATH，子进程就启不来。

如何判断：Cannot find module、Unexpected token，或在某个现代 JS 特性上报语法错。用 which node && node -v 确认。

6. 企业网络切断了连接

远程 MCP 走 HTTP/SSE，建立在一条长连接上。企业代理和防火墙会按固定间隔切掉空闲的长连接。

如何判断：掉线间隔很规律（每 30s 或 60s），而且只有远程 server 受影响。

7. macOS 防火墙拦了 server 的首次启动

新本地 server 第一次开 socket 时，macOS 会弹”允许传入连接”。如果你顺手点了 Deny，之后它就会静默失败。

如何判断：系统设置 → 网络 → 防火墙 → 选项里，看 Claude 或对应 server 是否被显式 block。

最短修复路径

Step 1：先看日志

别猜——断开那一行会告诉你该跑哪个修法。

Claude Desktop：

macOS:   ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\

边复现掉线边实时看 macOS 日志：

tail -n 50 -f ~/Library/Logs/Claude/mcp*.log

Claude Code：

claude --debug      # 输出详细的 MCP 启动日志
/mcp                # 会话内：显示每个 server 状态（connected / pending / failed）
/doctor             # 环境 + 配置体检

找最近一次断开时间附近的 MCP 日志，对照上面的分类表。

Step 2：配置里全用绝对路径

在 Claude Desktop 里，通过 Settings → Developer → Edit Config 打开配置（即 claude_desktop_config.json——macOS 在 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 在 %APPDATA%\Claude\claude_desktop_config.json）。Claude Code 的项目配置在项目根目录的 .mcp.json；local/user 范围的 server 在 ~/.claude.json。

一个正确的 stdio 配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/you/.nvm/versions/node/v22.14.0/bin/node",
      "args": [
        "/Users/you/code/mcp-filesystem/dist/index.js",
        "/Users/you/Documents"
      ]
    }
  }
}

能避开大多数掉线的几条规则：

• command 用 which node 拿到的绝对路径，绝不要写裸 "node"。
• args 里每个路径都是绝对路径——绝不用 ~ 或 ./。
• 路径里有空格就加引号或转义。
• JSON 必须合法。文件里任何一处多一个逗号、少一个括号，会静默地把所有 server 都干掉，而不只是你改的那个。如果 /mcp（或 Desktop 工具列表）里所有 server 同时失败，把文件贴进 JSON 校验器查一遍。

在 Claude Code 里你可以完全不手改文件：

# stdio server（-- 之后的内容原样传给 server）
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/Documents

claude mcp list          # 列出每个已配置 server 的状态
claude mcp get filesystem
claude mcp remove filesystem

Step 3：手动跑一次确认 server 能起来

把配置里的 command + args 原样复制到终端跑：

/Users/you/.nvm/versions/node/v22.14.0/bin/node \
  /Users/you/code/mcp-filesystem/dist/index.js \
  /Users/you/Documents

如果在终端里都崩，Claude 也起不来。先修运行时版本或装好依赖。想证明协议握手本身没问题（排除”Claude 提前关闭管道”那一类 bug），手动喂一个 initialize 请求进去：

echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
  | /Users/you/.nvm/versions/node/v22.14.0/bin/node /Users/you/code/mcp-filesystem/dist/index.js /Users/you/Documents

健康的 server 会回一个含 protocolVersion 和 capabilities 的 JSON result。没有回复就是 server 自己坏了；干净地回复了就说明问题出在 Claude 怎么启动它（路径、env 或超时）。

Step 4：修约 60 秒的启动超时

如果日志在约 60 秒处显示 Server transport closed 而没有真正报错，就是 server 没在窗口内完成初始化。

• 预装依赖，让启动不是一次冷安装。npx 类 server 先全局安装或在 package.json 里 pin 住版本；Puppeteer/Playwright 类 server 提前下好浏览器二进制，别在启动时才拉。
• 在 Claude Code 里，用 MCP_TIMEOUT 环境变量（毫秒）调高启动超时：

MCP_TIMEOUT=30000 claude     # 给 server 30 秒启动，而不是默认值

• 单次工具调用的超时（是某次工具调用跑太久，不是启动），在该 server 的 .mcp.json 条目里加 timeout 字段（毫秒），比如 "timeout": 600000 表示十分钟。这种情况见 Claude Code MCP 调用超时。

Step 5：远程 MCP 重新授权

工具调用返回 401 时：

• Claude Code：运行 /mcp，选中该 server，重新走一遍 OAuth。
• Claude Desktop：Settings → Connectors（或该 server 的条目）→ Disconnect → Connect，再授权。

授权后工具应立即可用。如果还是失败，检查上游平台（Slack/Linear/GitHub 等）的 admin 是否撤销了 App 授权，或者你配置里 --header "Authorization: Bearer …" 用的 bearer token 是否被轮换了。

Step 6：网络 / 防火墙

如果掉线很规律、且只命中远程 server，那是代理在切连接。让 IT 把 anthropic.com 和你 MCP 的具体域名（比如 mcp.notion.com、mcp.sentry.dev）加白名单，并停止切断到这些主机的空闲长连接。注意 SSE 传输在 2026 年已被标记弃用——如果 server 由你掌控，优先用 HTTP（streamable-http）传输，它对代理更友好。

排查被拦的本地 server（macOS）：

# 看 Claude 是否被应用防火墙拦了
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep -i claude

# 重置后重启 Claude，按提示点 Allow
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --remove /Applications/Claude.app

Step 7：对齐运行时版本

node -v        # 需要 >= 18；推荐 Node 22 LTS
python3 -V     # 需要 >= 3.10
which node     # 确认 Claude 会继承哪个二进制

如果装了多个版本，要么在 command 里写死绝对路径，要么在 server 的 env 里 pin 住 PATH：

{
  "command": "node",
  "args": ["/Users/you/code/mcp-filesystem/dist/index.js"],
  "env": {
    "PATH": "/Users/you/.nvm/versions/node/v22.14.0/bin:/usr/bin:/bin"
  }
}

如何确认修好了

1. 彻底退出并重启 Claude Desktop（Cmd+Q，不是只关窗口），或重启 Claude Code 会话——配置和 PATH 都是启动时读取的。
2. 在 Claude Code 里运行 /mcp（或 claude mcp list），确认 server 状态是 connected，不是 pending 或 failed。Desktop 里确认工具出现在工具列表中。
3. 真正调用一次该 server 的工具，看它返回结果。
4. 让会话空闲 3-5 分钟，再调一次工具。如果它能挺过空闲窗口，才算真正修好，而不是被一次新的重连掩盖了。

预防

• 配置里永远用绝对路径——绝不用 ~ 或 ./。
• pin 住 Node 版本（nvm + .nvmrc），别让系统或 Homebrew 升级把二进制从 Claude 脚下换掉。
• 预装 MCP 依赖，别指望启动时冷跑一次 npx 安装，这样才稳在启动窗口内。
• 每次改完配置，重启前先校验 JSON——一个坏逗号会拖垮所有 server。
• 把 .mcp.json / claude_desktop_config.json 纳入 git，改坏了能立刻回滚。
• 远程 MCP，把 token 过期时间记下来，过期前重新授权。

FAQ

每个 MCP server 一连上就失败——连官方的也是。怎么回事？ 如果所有 server 都在 initialize 之后立即失败（日志在几十毫秒内显示 Server transport closed，接着 Server disconnected. For troubleshooting guidance, please visit our debugging documentation），那几乎不是你的 server 的问题。常见诱因是配置里的 JSON 不合法（一处语法错就禁用全部），或 Claude Desktop / 系统级的启动 bug——比如在 macOS 26.2 Tahoe beta 上就报过这类回归，Desktop 在 initialize 后约 33ms 就关掉了管道。先校验 JSON；如果干净，把 Claude Desktop 更新到最新版，并去 anthropics/claude-code issues 查你系统对应的问题。

为什么远程 MCP 会自己重连，本地的不会？ 这是设计如此。HTTP 和 SSE server 用指数退避自动重连（Claude Code 最多重试五次）。stdio（本地子进程）server 不自动重连，所以本地崩溃在重启或重连前是永久的。需要韧性的话，能用远程 HTTP server 就优先用它。

server 连上了，但某次工具调用一直卡住，最后报错。 那是单次调用超时，不是连接掉线。在该 server 的 .mcp.json 条目里加 timeout 字段（毫秒），或设 MCP_TOOL_TIMEOUT。见 Claude Code MCP 调用超时。

配置和日志文件到底在哪？ Desktop 配置：macOS ~/Library/Application Support/Claude/claude_desktop_config.json，Windows %APPDATA%\Claude\claude_desktop_config.json（通过 Settings → Developer → Edit Config 打开）。Desktop 日志：~/Library/Logs/Claude/mcp*.log。Claude Code：项目配置在 .mcp.json，local/user 范围的 server 在 ~/.claude.json。

远程 server 该用 HTTP 还是 SSE 传输？ 用 HTTP（规范里叫 streamable-http）。SSE 在 2026 年已弃用——它还能用，但对 OAuth 和 claude mcp add --transport 标志的支持不如 HTTP，而且代理切它更狠。

相关阅读

• Claude Code MCP 调用超时
• Claude 工具不可用
• Claude Connector 权限
• Claude GitHub 连接失败

标签: #Claude #排查

相关文章

常见问题解决库

Claude Artifact 发完 follow-up 就回滚到旧版本

面板里手改了 Artifact，发一条新消息，它直接退回三轮前的版本。真正原因：你的面板修改根本没进 Claude 的记忆。先从 versions 下拉里把它捞回来，再让它别再发生。

2026/05/24 #Claude #排查

常见问题解决库

Claude Artifact 中 React 组件 prop 错误静默失败 —— 排查与修复

Claude 的 React artifact 预览空白、没有任何报错横幅。最快的办法:打开 DevTools 控制台(或点 'Try fixing with Claude')读出被吞掉的异常。逐个原因的完整排查指南。

2026/05/24 #排查 #Claude

常见问题解决库

Claude 附件预览不显示：修复空白缩略图

Claude 显示附件 tile 但没缩略图。多半是渲染延迟、不支持的格式（HEIC/TIFF）、或缓存脏了。最快修法和完整排查都在这。

2026/05/24 #Claude #排查

常见问题解决库

Claude 网页搜索引用点开 404 或跳错页

点 Claude 引用链接拿到 404、或落到无关页面。多半是 URL 被改写、原文挪了、或者付费墙——怎么救回真来源、验证事实本身。

2026/05/24 #Claude #排查

常见问题解决库

Claude Computer Use 在同一按钮上反复点击死循环 —— 排查与修复

Claude Computer Use 不停地点击同一个按钮或输入框迟迟无法推进,几乎都是截图时机、坐标缩放或隐藏状态的问题。本文先给最快的修复,再给完整诊断。

2026/05/24 #排查 #Claude

常见问题解决库

Claude 对话导出失败：PDF 空白页或数据导出收不到邮件

Print to PDF 存出来是空白页，或者 Settings > Privacy 的 Export data 一直不发下载链接。多半是线程太长、Artifact 渲染失败、或导出任务卡住——每种情况都给出对应修法。

2026/05/24 #Claude #排查