Chrome MCP

架构总览

Claude Code (stdio)
  → chrome-mcp-proxy.sh
    → chrome-devtools-mcp (连接 proxy 的 WebSocket)
      → cdp-proxy.mjs v3 (port 9401)
          ├── 持久 WebSocket 连接到 Chrome（弹窗只出现一次）
          ├── 请求 ID 重映射（防多客户端冲突）
          ├── 事件按 sessionId 路由（防多 Agent 互扰）
          └── 拦截抢焦点命令
        → 真实 Chrome (通过 DevToolsActivePort 文件连接)

核心原则：必须通过 proxy 中间层，绝不直连 Chrome。

铁律（绝不可违反）

1. 必须经过 proxy

• proxy (cdp-proxy.mjs) 拦截 Target.activateTarget 和 Page.bringToFront，防止浏览器抢用户焦点
• 强制 createTarget 在后台创建 tab（background: true）
• .mcp.json 中 chrome 配置必须用 chrome-mcp-proxy.sh，不能用 chrome-devtools-mcp 直连

2. 必须连接真实浏览器

• 用户日常使用的 Chrome（有登录态、插件、书签）
• Chrome 需在 chrome://inspect/#remote-debugging 中开启远程调试（一次性设置）
• proxy 通过读取 ~/Library/Application Support/Google/Chrome/DevToolsActivePort 文件自动连接
• 绝对禁止用 --user-data-dir=/tmp/xxx 或 ~/.cache/chrome-devtools-mcp/chrome-profile 启动无状态 Chrome

3. 不走网络代理

• .mcp.json 中 chrome 服务不配 env 代理变量
• chrome-mcp-proxy.sh 脚本内部已 unset 所有代理环境变量
• 本机 zshrc 有全局代理 (http_proxy=127.0.0.1:7897)，会拦截本地连接，所以必须 unset

4. 绝不杀当前 session 的 MCP 进程

• Chrome MCP 是 Claude Code 通过 stdio 管道启动的子进程
• 进程一死，管道断裂，当前 session 永远无法恢复
• 清理多实例只用安全脚本: bash ~/scripts/kill-old-chrome-mcp.sh

5. proxy 是持久服务

• proxy 用 nohup + disown 启动，不随 Claude Code 退出而死
• 启动时立即建立到 Chrome 的持久 WebSocket 连接
• 所有 Claude Code 会话共用这一条连接
• Chrome 断开后自动每 5 秒重连

6. 绝不在 MCP server 配置里用 npx -y chrome-devtools-mcp@xxx（2026-05-26 新增）

• 本机的 npx -y 在 MCP host stdio spawn 环境下会永久 hang，根本不 spawn binary，导致 30s timeout
• 同样症状跨所有版本：@latest (1.0.x) / @0.19.0 都中招
• 触发条件不明，疑为 ~/.npm/_locks/ stale lock 或 npm registry metadata 探测被某状态阻塞
• 正确写法：3 个 proxy 脚本末尾的 fallback 模板

  CDP_MCP_BIN="$HOME/.npm/_npx/a44f1c2f3c68e710/node_modules/.bin/chrome-devtools-mcp"
  if [ -x "$CDP_MCP_BIN" ]; then
      exec "$CDP_MCP_BIN" --browserUrl "http://127.0.0.1:${PROXY_PORT}"
  else
      exec npx -y chrome-devtools-mcp@0.19.0 --browserUrl "http://127.0.0.1:${PROXY_PORT}"
  fi

• 任何新 Agent 的 MCP 配置（Codex / Cursor / Cline / 别的）都要走 proxy 脚本，不要直接配 command="npx"

Chrome 146+ 远程调试弹窗问题

问题

Chrome 146 开始，外部程序通过 WebSocket 连接调试端口时，Chrome 会弹出"要允许远程调试吗？"授权窗口。每次新建 WebSocket 连接都会弹一次。

解决方案：持久连接

cdp-proxy.mjs v3 在启动时就建立一条持久连接到 Chrome，所有客户端共用。弹窗只在以下情况出现：

• proxy 首次启动时（点一次"允许"）
• Chrome 重启后 proxy 重连时（点一次"允许"）

之后新开 Claude Code 窗口不再弹窗，因为复用已有连接。

前置条件

Chrome 地址栏打开 chrome://inspect/#remote-debugging，勾选 Allow remote debugging for this browser instance（一次性设置）。

无效方案（已验证不可行）

多 Agent 隔离（v3 新增）

多个 Agent（或 sub-agent）同时操作 Chrome 时，proxy v3 保证互不干扰：

架构上，所有 Agent 共享同一个 Chrome、同一个 proxy，各自创建后台 tab，通过不同的 sessionId/targetId 操作，互不干扰。

配置文件

~/.mcp.json（chrome 部分）

"chrome": {
  "command": "bash",
  "args": [
    "/Users/wangkai/scripts/chrome-mcp-proxy.sh",
    "9401",
    "9222"
  ]
}

注意：不要加 env 代理变量！

~/.claude/settings.json（权限）

MCP 工具权限不能用通配符 mcp__chrome__*（会导致整个 settings 文件被跳过），必须逐一列出：

"permissions": {
  "allow": [
    "mcp__chrome__click",
    "mcp__chrome__close_page",
    "mcp__chrome__take_screenshot",
    ...
  ]
}

~/.claude/settings.local.json（MCP 启用）

同样需要逐一列出 MCP 工具名，不能用通配符。

关键脚本

关键文件

排障流程

症状：Chrome MCP 工具报错 "Could not connect to Chrome"

步骤1: 检查 Chrome 是否在运行

pgrep -x "Google Chrome" && echo "running" || echo "not running"

没运行就启动：open -a "Google Chrome"

步骤2: 检查 DevToolsActivePort 文件

cat ~/Library/Application\ Support/Google/Chrome/DevToolsActivePort

步骤3: 检查 proxy 状态

curl -s --noproxy '*' http://127.0.0.1:9401/proxy/status

应该看到 chromeConnected: true。如果是 false，Chrome 可能需要点一次"允许"弹窗。

步骤4: 用 /mcp 重连

步骤5: 安全清理旧进程

bash ~/scripts/kill-old-chrome-mcp.sh

步骤6: 最后手段 — 退出重启 Claude Code

症状：每次开新 Claude Code 都弹远程调试弹窗

检查 proxy 是否在持久运行：

curl -s --noproxy '*' http://127.0.0.1:9401/proxy/status

如果 proxy 没在运行，说明上次退出时被杀了。手动启动：

unset http_proxy HTTP_PROXY https_proxy HTTPS_PROXY all_proxy ALL_PROXY
nohup node ~/scripts/cdp-proxy.mjs --port 9401 --chrome-port 9222 &>~/chrome-profiles/logs/proxy-9401.log &
disown

然后在 Chrome 点一次"允许"，之后就不再弹了。

症状：感觉 "DevTools 协议被占满"（命令变慢/超时）

/proxy/status 看 sessions 数，如果远大于 tabs 总数，说明有客户端 session 泄漏（老 Claude Code 窗口关的时候 chrome-devtools-mcp 没 detach 干净）。

• v3.1 后 proxy 自带空闲回收：idle > 5min 自动 detach 全部 session
• 想立即清理：关掉闲置 Claude Code 窗口（触发 clientDisconnect），或在闲置窗口里 /mcp disable chrome
• 重启 proxy 是最暴力的清理（但所有窗口都要重连）

症状：多 Agent 操作时互相干扰

检查 proxy 版本是否为 v3：

curl -s --noproxy '*' http://127.0.0.1:9401/proxy/status

v3 会返回 sessions 和 clientDetails 字段。如果没有，需要重启 proxy 加载新版 cdp-proxy.mjs。

症状：/mcp reconnect 30 秒 timeout，但 proxy/status 显示 chromeConnected: true（2026-05-26 新增 — npx -y hang）

特征：

• Claude Code 交互窗口 /mcp 重连 chrome / beta / arc 任一 server → connection timed out after 30000ms
• proxy /proxy/status 显示 chromeConnected: true, clients: 0
• proxy 日志没有任何"客户端连接"事件，新 MCP client 从未到达 proxy
• chrome-devtools-mcp 孤儿进程数量正常 / 全清也不解决
• Codex 那边 chrome MCP 同样症状

根因：npx -y chrome-devtools-mcp@xxx 在 MCP host stdio spawn 环境下永久 hang，根本不 spawn binary。npx 卡在某个 metadata / lock 阶段不返回。

快速判定（30 秒）：

# 直接调 cache binary 测 handshake
BIN=$(find ~/.npm/_npx -name "chrome-devtools-mcp" -type l -path "*/node_modules/.bin/*" 2>/dev/null | head -1)
cat <<'EOF' > /tmp/mcp-init.txt
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
EOF
timeout 10 bash -c "(cat /tmp/mcp-init.txt; sleep 8) | $BIN --browserUrl http://127.0.0.1:9402" | head -3
# 秒回 initialize response = binary OK，proxy OK，问题在 npx
# 同样测 `npx -y chrome-devtools-mcp@0.19.0` 30s 没输出 = npx hang 确诊

修复：3 个 proxy 脚本末尾改为"优先 cache binary，fallback npx"（见铁律 §6 模板）。改完 /mcp reconnect 立即秒连。

禁忌：

• 不要再尝试杀 zombie / 重启 proxy / 改 chrome-devtools-mcp 版本 — 这些都不是根因
• 不要直接配 command="npx" 在任何 agent 的 mcp config 里 — 同坑

症状：所有工具都报 "No page selected"（chrome-devtools-mcp 0.24.0 init 死锁）

特征：

• proxy /proxy/status 显示 chromeConnected: true，clients ≥ 1，但对应 client sessions: 0, tabs: 0
• Chrome curl http://127.0.0.1:9402/json/list 能看到真实 page targets
• 但 list_pages / new_page / select_page 全部报 No page selected

根因（chrome-devtools-mcp 0.24.0 代码逻辑）：

• index.js:210 每个 tool call 先调 getSelectedMcpPage()，没选中就抛 No page selected
• 唯一会 auto-select 的路径是 McpContext.#init() → createPagesSnapshot()，但只有 puppeteer init 当时能看到 page 才会 select
• Chrome 重启 + chrome-devtools-mcp spawn 时序冲突 → puppeteer init 时 0 page → 永久死锁
• 没有事件监听器（browser.on('targetcreated') 不存在），后续 Chrome 开 tab 也不会触发刷新

修复：必须重启 chrome-devtools-mcp 让 puppeteer 在 Chrome 已有 page 时重 init

1. 确认 Chrome 已有真实 page：curl -s http://127.0.0.1:9402/json/list | jq '.[] | select(.type=="page")'
2. Claude Code 里 /mcp 把对应 server（如 beta）disable 再 enable
3. 验证：调 list_pages 应返回 [selected] 标记的 page

禁忌：

• 不要直接 kill chrome-devtools-mcp 进程，stdio 管道断了 Claude Code 不会自动 respawn
• /mcp 是唯一干净的重启路径

历史事故教训

多 Agent 物理隔离方案（2026-05-26 推荐）

为避免多 agent（Claude Code / Codex / Cursor / ...）抢同一个 proxy 撞 init 死锁、版本冲突、CDP session 池竞争，采用物理隔离：

原则：

1. 一个 proxy 端口对应一个浏览器实例
2. 多个 agent 可以共用同一 proxy（proxy v3 多 client 设计），但仅当确定它们用同一版本 chrome-devtools-mcp 且都走 binary（不走 npx -y）
3. 业务场景天然区分时（如 Codex 跑业务页 / Claude Code 跑社媒页），直接物理隔离最稳

配置示例（Codex ~/.codex/config.toml）：

[mcp_servers.chrome]
# 通过脚本启动，绝不直接 npx
command = "bash"
args = ["/Users/wangkai/scripts/chrome-mcp-proxy.sh", "9401", "9222"]

反例（永远不要这么写）：

[mcp_servers.chrome]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9402"]
# ❌ 1. npx -y 在本机 hang（铁律 §6）
# ❌ 2. @latest 是 1.0.x，有 0.24.0+ init 死锁（§历史事故 2026-05-05）
# ❌ 3. 共享 9402 跟 Claude Code beta 抢资源