Chrome MCP

1. Chrome MCP 完整运维指南

Chrome MCP 完整运维知识库，含连接排障、多实例管理、进程保护铁律

Prompt

---
name: Chrome MCP 完整运维 Skill
description: Chrome MCP 架构、配置、排障、铁律 — 涵盖 proxy v3 防抢焦点、持久连接、多 Agent 隔离、Chrome 146 弹窗解决方案
type: reference
---

# Chrome MCP 完整运维 Skill

## 架构总览

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 秒重连

## 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**（一次性设置）。

### 无效方案（已验证不可行）
| 方案 | 结果 |
|------|------|
| `--remote-debugging-port=9222` | Chrome 146 要求 `--user-data-dir` 为非默认目录，丢失登录态 |
| `--silent-debugger-extension-api` | 对远程调试弹窗无效 |
| `--disable-features=AutomationControlled` | 对弹窗无效 |
| `defaults write com.google.Chrome DevToolsRemoteDebuggingAllowed` | Chrome 不读取 |
| macOS managed preferences plist | Chrome 不读取 |
| `.mobileconfig` 配置描述文件 | Chrome 不读取 |
| `devtools.remote_debugging.allowed` in Local State | 无效 |
| `chrome-devtools-mcp --autoConnect` | 仍然弹窗 |
| 锁定 chrome-devtools-mcp 旧版本 (0.19.0) | 无效 |

## 多 Agent 隔离（v3 新增）

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

| 机制 | 说明 |
|------|------|
| **请求 ID 重映射** | 每个客户端的请求 ID 统一映射为全局唯一 ID，响应精准路由回原客户端 |
| **事件按 sessionId 路由** | `Target.attachToTarget` 的 session 归属记录到对应客户端，后续该 session 的事件只发给该客户端 |
| **Tab 归属追踪** | `Target.createTarget` 的响应记录 tab 归属，Target 域的全局事件按 targetId 路由 |
| **客户端断开清理** | 客户端断开时清理其 session 归属、未完成请求、tab 记录 |

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

## 配置文件

### ~/.mcp.json（chrome 部分）
```json
"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 点一次"允许"，之后就不再弹了。

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

检查 proxy 版本是否为 v3：

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

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

历史事故教训