Claude Code 跑 MCP 报Tool execution timeout多半是卡在 Playwright 这类重工具上先别急着换 MCP Server把手上的模型请求切到 TaoToken 这条统一兼容通道排障会更干净。打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 API Key把 Claude Code 的 Base URL 指过去再回来调超时参数才能分清楚是模型通道不稳定还是本地 MCP 工具本身就慢。TaoToken 不替你打开浏览器也不执行 MCP 动作它只统一接管模型 API 调用让官方通道限流、Key 失效、网络抖动这些变量先退出排障现场。等通道稳定后再看报错场面通常是browser_navigate跑出去30 秒后抛一句Tool execution timeout: browser_navigate exceeded 30000ms timeout紧接着MCP tool playwright is not responding。手动跑同一个操作没问题一进 Claude Code 就被 30 秒阈值截断问题大多出在浏览器启动慢、MCP Server 卡死或超时阈值太低。把~/.claude/settings.json里的toolTimeout调到 120000、mcpTimeout调到 60000很多这类超时能直接消失。1. 先看报错Tool execution timeout 卡在 browser_navigate1.1 报错现场Claude Code 里跑 Playwright 截图或抓数据最常见的内容是这样的Tool execution timeout: browser_navigate exceeded 30000ms timeout MCP tool playwright is not responding Timeout waiting for tool response (30000ms)有的版本还会在超时后补一句The MCP server may be unresponsive。表现出来就是你让它「打开网页并截图」它在browser_navigate这一步干等最后直接断开之前已经拿到的页面状态也丢了。更麻烦的是这种超时不是偶发而是同一个 MCP Server 反复卡在同一个工具上导致后续对话里的其他工具调用也被拖慢。这类报错高发在几个场景Playwright 启动 Chromium 进程首次启动往往要 10 到 30 秒MCP 工具发起网络请求目标网站响应很慢MCP Server 内存占用高进程假死工具要做的动作太多比如一次文件搜索遍历整个项目MCP Server 和 Claude Code 之间的 stdio 通信被大量日志堵住。你可以在日志里看到请求已经发出但 MCP Server 一直没有把结果写回最终 Claude Code 主动断开。1.2 先确认 MCP Server 本身还活着吗在改任何配置前先手动测一次 MCP Server。这个动作能帮你快速站队到底是工具操作慢还是 Server 已经死了。echo {jsonrpc:2.0,method:tools/list,id:1} | npx -y executeautomation/playwright-mcp-server如果这个命令很快返回一组tools列表说明 Server 本身没问题超时是特定操作太慢如果命令一直挂着不返回说明 Server 已经卡死后文先重启再看。这一步也是排查清单里性价比最高的一个动作基本能排除掉一半「假死」型超时。手动测试通过之后再回到 Claude Code 里重试如果重试仍然超时就要去看超时阈值和依赖状态了。2. 为什么会超时30 秒阈值、浏览器启动、进程卡死2.1 超时链路Claude Code 调用 MCP 工具走的是一条很直接但不快的链路Claude Code 通过 stdio 向 MCP Server 发送 JSON-RPC 请求MCP Server 拿到请求后去启动浏览器、发网络请求或扫描文件做完再把结果写回 stdout。Claude Code 这边有个默认 30 秒的工具超时阈值只要 MCP Server 在 30 秒内没把结果送回来Claude Code 就认为这次调用失败主动断开连接。后面哪怕浏览器已经打开了结果也送不回去。这个链路里最脆弱的两环一个是 MCP Server 启动浏览器的时间一个是 MCP Server 和 Claude Code 之间单向管道的数据吞吐。只要有一环超过 30 秒整个调用就会被判死。尤其 Playwright 的browser_navigate它不只是启动浏览器还要等页面 load 事件遇到重页面或慢接口10 秒起步是常态卡到 30 秒以上也经常发生。2.2 原因分类与优先级根据经验可以按概率把常见原因排个序原因具体表现大致占比MCP 工具操作慢浏览器启动、页面加载、网络请求慢约 40%MCP Server 卡死内存泄漏、死锁、进程假死约 25%stdio 通信阻塞MCP Server 往 stdout 输出日志缓冲区满约 15%超时阈值过低默认 30 秒不够复杂操作约 10%网络不稳定目标网站响应超时或丢包约 5%MCP Server bug工具内部异常导致卡住约 5%占比不用记死但要记住一件事浏览器启动慢和 Server 卡死加起来占了超过一半。所以排障顺序应该是先确保通道稳定再调大超时然后处理 Server 本身的健康状态。如果一上来就直接重装 MCP Server反而会掩盖「只是阈值太低」这类简单问题。反过来只调大超时却不看 Server 是否卡死也容易把一个已经死掉的进程留到下次报错。3. 先把通道切到 TaoToken超时排障的第一步3.1 去官网注册并创建 API Key打开 TaoToken 注册账号进控制台创建一个 API Key复制后保存好。这里的地址是官网落地页用来注册、创建 Key、看模型广场和用量真正填进工具的接口地址是另一回事别混。创建时注意API Key 只会完整显示一次保存成YOUR_API_KEY占位符也没关系后续配置文件里统一用它。模型 ID 不要凭记忆乱填以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场实际列出的为准避免在配置文件里写一个自己以为存在、实际上通道里不支持的版本号。3.2 把 Claude Code 的 Base URL 换成 TaoTokenClaude Code 默认连的是 Anthropic 官方接口现在改成走 TaoToken 的兼容通道。编辑~/.claude/settings.json在env块里加三项{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }注意ANTHROPIC_BASE_URL填的是 https://taotoken.net/api末尾不要加/v1也不要带任何 UTM 参数。ANTHROPIC_MODEL的值以模型广场为准。如果你平时用 CC Switch 这类工具管理多套 Claude Code 配置自定义供应商的 Base URL 填同一个 https://taotoken.net/apiKey 填同一个YOUR_API_KEY。这一步的核心价值是让 Claude Code 的模型请求走一条稳定的统一接入通道不在工具超时排障时被通道问题干扰。3.3 命令行快速验证 Key 能不能通想先确认 Key 和模型 ID 是否匹配可以用 TaoToken 的 CLI 快速打一次npm install -g taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID能正常返回内容说明模型通道已经通了接下来调 MCP 超时时可以放心排除「官方额度不够」「Key 配错」「Base URL 写错」这几类干扰。如果这里就报 401回官网控制台重新检查 Key别急着调settings.json。这里再强调一下边界TaoToken 不执行任何浏览器或 MCP 动作它只负责统一接管模型 API 请求。换句话说切到 TaoToken 之后如果 MCP 还是超时那基本可以断定问题出在本地工具链而不是模型通道。4. 核心修复在 settings.json 里调大 toolTimeout 和 mcpTimeout4.1 给 Claude Code 配一份完整的带超时配置通道切好后再把超时参数合进配置文件。打开~/.claude/settings.json最终内容类似{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID }, toolTimeout: 120000, mcpTimeout: 60000 }toolTimeout管的是单次工具调用的总时长mcpTimeout管的是 MCP Server 响应前的最长等待时间。Playwright 要拉起一个完整的 Chromium首次启动 10 到 30 秒很常见再加页面加载 10 秒30 秒默认值确实不够。给到 120000 和 60000 之后绝大多数「工具确实慢但没死」的超时都能过去。改完必须重启 Claude Code。/exit退出当前会话再重新运行claude。只重开对话窗口不够配置文件是启动时加载的不重启的话即使改了参数也还是老阈值生效。4.2 环境变量方式的临时替代如果不想长期改settings.json只是想在 CI 或临时环境里试一次可以这样export CLAUDE_TOOL_TIMEOUT120000 claudeCI 环境资源更紧张也可以把CLAUDE_TOOL_TIMEOUT给到 180000给慢工具留更多余量。但注意环境变量方式适合临时排查本机长期使用还是建议把toolTimeout和mcpTimeout写在settings.json里避免每次开终端都要重新 export。还有一种情况是你在 Docker 容器里跑 Claude Code容器内的 Chromium 依赖可能没装齐这时候光调超时没用要在镜像里补浏览器依赖后文会提到。5. 继续排查MCP Server 卡死、依赖缺失、重活拆单步5.1 MCP Server 卡死先重启再重建如果调大超时后依然在同一个位置超时优先怀疑 MCP Server 已经进入假死状态。先在 Claude Code 里执行/mcp restart不生效就退出 Claude Code 再进来。仍然不行直接重建这个 MCPclaude mcp remove playwright claude mcp add-json playwright {command:npx,args:[-y,executeautomation/playwright-mcp-server]}重建之后重新测试那个操作。MCP Server 卡死的典型原因是内存泄漏或死锁定期重启虽然治标不治本但在排障阶段是恢复效率最高的手段。如果重建后还是卡建议用ps aux | grep mcp看进程状态确认是不是有多个残留 MCP 进程在抢资源顺手把没有用的旧进程清掉。5.2 预装浏览器和 MCP 依赖很多首次超时不是 Server 卡死而是本地缺依赖MCP Server 启动时现场下载 Chromium。预装一遍能省掉这个等待npx playwright install npm install -g executeautomation/playwright-mcp-server装完后用第 1 章那条tools/list命令再测一次响应速度如果快速返回说明工具链已经就绪如果还是慢再往下查。Docker 环境里还要多一步在 Dockerfile 里补上RUN npx playwright install --with-deps chromium否则容器里缺系统库浏览器还是起不来。预装依赖解决的是「首次启动慢」这一类问题它和调大超时是互补的不冲突。5.3 复杂操作拆成单步执行不要一次给 MCP 工具安排「打开网页、等待加载、截图、提取文本、关闭浏览器」五连动作。MCP 工具执行是线性的单步超时会让整条结果全部丢弃。拆成四步第 1 步打开网页第 2 步确认加载完成再截图第 3 步提取文本第 4 步关闭浏览器。每步等结果确认后再发下一个指令。这样即使某一步超时损失也只有那一步不会把前面的页面状态一起丢掉。实际写 prompt 的时候也尽量一件事一句话不要用「然后」把一堆动作串起来。5.4 查看 MCP 日志和 debug 输出需要查根因时看日志比瞎猜快cat ~/.claude/logs/mcp-*.log还不够就用 debug 模式启动 Claude Codeclaude --debugdebug 模式下 MCP Server 的 stderr 输出会直接显示在终端里。常见的日志杀手是 MCP Server 自己往 stdout 打印的日志MCP 依赖 stdin/stdout 和 Claude Code 通信一旦 Server 把无关信息打进 stdout缓冲区满了之后通信就会阻塞表现同样是超时。确保 MCP Server 不要输出与协议无关的日志这也是很多「莫名其妙超时」的真正根因。6. 方案对比、排查清单与 FAQ 速查6.1 方案对比把前面提到的方案放一起看方便按场景选方案适用场景难度调大 toolTimeout / mcpTimeout操作本身确实慢低/mcp restart 重启 ServerMCP Server 卡死低预装 Playwright 和依赖首次启动慢、依赖未装中换成更轻量的工具Playwright 太重只想要抓取中复杂操作分步执行单次操作链路太长低查看 MCP 日志和 debug原因不明需要深度排查中如果确认是 Playwright 本身太重比如你只是抓一个静态页面的文本可以考虑用 fetch MCP 替代浏览器类工具命令是claude mcp add-json fetch {command:npx,args:[-y,modelcontextprotocol/server-fetch]}。这是最后手段先调超时和重启再决定要不要换。6.2 排查清单速查表把 Claude Code 的模型请求切到统一 API 通道确认 Key 能通在settings.json里调大toolTimeout到 120000、mcpTimeout到 60000重启 Claude Code用/mcp restart重启对应 MCP Server预装依赖npx playwright install手动用tools/list测试 Server 响应复杂操作拆成单步执行查看~/.claude/logs/mcp-*.log用claude --debug观察 stderr检查系统内存和 CPUDocker 环境记得装 Chromium 依赖。6.3 FAQ 速查默认工具超时是多少Claude Code 默认 30 秒。对 Playwright 这类需要启动浏览器的工具30 秒不够用。怎么区分工具慢还是 Server 卡死手动运行 MCP Server 并发送tools/list。快速返回说明 Server 正常只是本次操作慢一直不返回说明 Server 卡死。MCP Server 内存泄漏怎么办没有一劳永逸的修复先用/mcp restart恢复再考虑给 Server 加定期重启策略或换一个实现。stdio 通信阻塞是什么MCP Server 通过 stdin/stdout 和 Claude Code 通信。Server 如果往 stdout 写非协议内容缓冲区满了会把整条链路堵住。避免在 Server 代码里用console.log输出普通日志。切到 TaoToken 之后还要调toolTimeout吗要。TaoToken 只负责模型 API 通道不参与 MCP 工具的超时控制。通道稳定只是帮你排除一类干扰工具超时仍然由 Claude Code 本地参数决定。7. 写在最后一套可复用的超时处理节奏7.1 我的建议处理顺序先切通道再调参数最后查本地。具体来说去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 API Key把 Base URL 指到 TaoToken然后在settings.json里把toolTimeout和mcpTimeout调大重启后重试。这一步能解决至少一半的「工具执行超时」。如果还超时/mcp restart重启 Server操作确实慢就预装依赖链路太长就拆步日志有异常就清理 stdout 输出。这样一层层排除最后剩下的才是真正需要换工具的硬骨头。7.2 什么时候别只调超时调大超时不是万能的。MCP Server 内存泄漏导致进程越来越慢时调大超时只是把报错时间往后拖stdio 被日志堵住时调大超时无效反而让你等更久。这两种情况要优先处理 Server 本身的健康状态。另外也别把toolTimeout调到 600000 这种天文数字一旦 MCP Server 真的卡死你只会等得更痛苦。120000 是一个比较均衡的折中既能覆盖浏览器慢启动又不会让无效等待拖垮整个排障节奏。7.3 去控制台确认本次调用是否上账配置生效后找个 Playwright MCP 任务再跑一次。如果这次不超时了打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 登录控制台看刚才那次模型调用有没有进入用量记录。有记录说明通道和模型 ID 都没问题整个链路是通的没有记录回去检查YOUR_API_KEY是否复制完整、ANTHROPIC_BASE_URL是否多写了路径。控制台地址和接口地址是两回事往 Claude Code 里填的永远是 https://taotoken.net/api不带/v1不带 UTM。如果用量记录里已经有刚才那一次调用说明通道稳定MCP 超时确实来自本地工具链回到上面的排查清单继续处理 Server 侧的问题就好。