【Bug已解决】Tool execution timeout / MCP tool hangs — Claude Code 工具执行超时解决方案

1. 问题描述

在 Claude Code 中调用工具（特别是 MCP 工具）时，工具长时间无响应，最终超时报错：

Tool execution timeout: browser_navigate exceeded 30000ms timeout

或者：

MCP tool 'playwright' is not responding
Timeout waiting for tool response (30000ms)

有时表现为工具执行后卡住：

> 使用 playwright 打开网页并截图
# ... 长时间等待 ...
Tool execution timeout
The MCP server may be unresponsive

这个问题在以下场景中特别常见：

• Playwright 等 MCP 工具需要打开浏览器，启动慢
• MCP 工具执行网络请求，目标网站响应慢
• MCP Server 内存不足或进程卡死
• 工具执行复杂操作（如大量文件搜索）
• MCP Server 与 Claude Code 之间的 stdio 通信阻塞

2. 原因分析

核心原理拆解

Claude Code 调用 MCP 工具 → 通过 stdio 发送请求
        ↓
MCP Server 执行操作（浏览器/网络/文件）
        ↓
操作执行时间超过工具超时阈值（默认 30 秒）
        ↓
Claude Code 超时断开
        ↓
报错 Tool execution timeout

原因分类表

原因分类	具体表现	占比
MCP 工具操作慢	浏览器启动、网络请求等	约 40%
MCP Server 卡死	进程内存泄漏或死锁	约 25%
stdio 通信阻塞	输出缓冲区满	约 15%
超时阈值过低	默认 30 秒不够	约 10%
网络不稳定	工具的网络请求超时	约 5%
MCP Server 版本 bug	工具内部错误导致卡住	约 5%

3. 解决方案

方案一：增加工具超时时间（最推荐）

# 步骤 1：在 settings.json 中增加超时
cat > ~/.claude/settings.json << 'EOF'
{
  "toolTimeout": 120000,
  "mcpTimeout": 60000
}
EOF

# 步骤 2：或在环境变量中设置
export CLAUDE_TOOL_TIMEOUT=120000

# 步骤 3：重启 Claude Code
claude

方案二：重启 MCP Server

# 步骤 1：在 Claude Code 中重启 MCP
/mcp restart

# 步骤 2：或退出 Claude Code 重新进入
/exit
claude

# 步骤 3：如果 MCP Server 仍然卡死
claude mcp remove playwright
claude mcp add-json playwright '{"command":"npx","args":["-y","@executeautomation/playwright-mcp-server"]}'

方案三：预启动 MCP 工具依赖

# 步骤 1：预安装 Playwright 浏览器
npx playwright install

# 步骤 2：预安装所有依赖
npm install -g @executeautomation/playwright-mcp-server

# 步骤 3：手动测试 MCP Server 响应速度
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx -y @executeautomation/playwright-mcp-server
# 如果响应快，说明工具本身没问题

方案四：使用更快的替代工具

# 步骤 1：如果 Playwright 太慢，使用更轻量的工具
claude mcp remove playwright
claude mcp add-json puppeteer '{"command":"npx","args":["-y","@modelcontextprotocol/server-puppeteer"]}'
# Puppeteer 比 Playwright 启动更快

# 步骤 2：或使用 fetch MCP 替代浏览器
claude mcp add-json fetch '{"command":"npx","args":["-y","@modelcontextprotocol/server-fetch"]}'

方案五：分步执行避免超时

# 不要一次性执行复杂操作:
> 打开网页、等待加载、截图、提取文本、关闭浏览器

# 分步执行:
> 步骤 1: 打开网页
# 等待完成
> 步骤 2: 截图
# 等待完成
> 步骤 3: 提取文本
# 等待完成
> 步骤 4: 关闭浏览器

方案六：检查 MCP Server 日志

# 步骤 1：查看 MCP 日志
cat ~/.claude/logs/mcp-*.log

# 步骤 2：以 debug 模式启动查看详细日志
claude --debug

# 步骤 3：查看 MCP Server 的 stderr 输出
# debug 模式会显示 MCP Server 的错误输出

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：增加超时	操作确实慢	⭐⭐⭐⭐⭐	低
方案二：重启 MCP	Server 卡死	⭐⭐⭐⭐⭐	低
方案三：预装依赖	首次启动慢	⭐⭐⭐⭐	中
方案四：替代工具	工具太重	⭐⭐⭐	中
方案五：分步执行	复杂操作	⭐⭐⭐⭐	低
方案六：查看日志	深度排查	⭐⭐⭐	中

5. 常见问题 FAQ

5.1 默认工具超时是多少

默认工具超时为 30 秒。对于 Playwright 等需要启动浏览器的工具，30 秒可能不够。

5.2 如何区分是工具慢还是 Server 卡死

手动运行 MCP Server 并发送请求：

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx -y @executeautomation/playwright-mcp-server

如果快速响应，说明 Server 正常，是特定工具操作慢。如果不响应，说明 Server 卡死。

5.3 MCP Server 内存泄漏怎么办

MCP Server 进程可能因内存泄漏逐渐变慢。定期重启 MCP Server：

/mcp restart

5.4 stdio 通信阻塞是什么

MCP 通过 stdin/stdout 通信。如果 MCP Server 输出大量数据（如 console.log），stdout 缓冲区可能满，导致通信阻塞。确保 MCP Server 不输出无关的日志。

5.5 Playwright MCP 为什么慢

Playwright 需要启动完整的浏览器进程（Chromium），首次启动可能需要 10-30 秒。预安装浏览器和依赖可以加速。

5.6 多个 MCP 工具同时超时

可能是系统资源不足。检查内存和 CPU 使用：

ps aux | grep mcp
top

5.7 CI/CD 中工具超时

CI 环境资源有限，增加超时或减少 MCP 工具使用：

export CLAUDE_TOOL_TIMEOUT=180000

5.8 工具超时后 MCP Server 状态

工具超时后，MCP Server 进程仍然运行，但可能处于不一致状态。建议重启 MCP Server 后继续。

5.9 Docker 中 MCP 工具超时

Docker 容器可能缺少浏览器依赖。在 Dockerfile 中安装：

RUN npx playwright install --with-deps chromium

5.10 排查清单速查表

□ 1. 增加 settings.json 中的 toolTimeout 和 mcpTimeout
□ 2. 使用 /mcp restart 重启 MCP Server
□ 3. 预安装工具依赖（如 npx playwright install）
□ 4. 手动测试 MCP Server 响应速度
□ 5. 复杂操作分步执行
□ 6. 查看 ~/.claude/logs/mcp-*.log 日志
□ 7. 使用 --debug 模式查看详细输出
□ 8. 考虑更轻量的替代工具
□ 9. 检查系统资源（内存/CPU）
□ 10. Docker 中安装浏览器依赖

6. 总结

1. 根本原因：工具执行超时最常见原因是 MCP 工具操作慢（40%，如浏览器启动）和 MCP Server 卡死（25%，内存泄漏或死锁）
2. 最佳实践：在 settings.json 中将 toolTimeout 增加到 120 秒，为慢速工具留出足够时间
3. 快速恢复：使用 /mcp restart 重启 MCP Server，解决因卡死导致的超时
4. 预防措施：预安装 MCP 工具依赖（如 npx playwright install），避免首次启动时下载依赖导致超时
5. 最佳实践建议：将复杂的多步 MCP 操作拆分为单步执行，每步完成后确认结果再继续，避免单次操作过于复杂导致超时

故障排查流程图

flowchart TD
    A[Tool execution timeout] --> B{是首次使用该工具?}
    B -->|是| C[预安装依赖: npx playwright install]
    B -->|否| D{MCP Server 是否卡死?}
    C --> E[重启 Claude Code]
    D --> F[手动测试 MCP Server]
    F --> G{Server 响应快?}
    G -->|是| H[增加 toolTimeout]
    G -->|否| I[重启 MCP Server]
    E --> J[重试操作]
    H --> J
    I --> J
    J --> K{超时消失?}
    K -->|是| L[✅ 问题解决]
    K -->|否| M[分步执行操作]
    M --> N{每步是否超时?}
    N -->|否| L
    N -->|是| O[考虑替代工具]
    O --> P[移除慢速 MCP Server]
    P --> Q[添加轻量替代]
    Q --> L