OpenCode + Chrome DevTools MCP 使用说明

前置条件

• Node.js >= 20
• Chrome 浏览器
• 已安装 chrome-devtools-mcp（首次运行自动安装）

---

第一步：Chrome 开启远程调试

1. 正常打开 Chrome（不需要任何命令行参数）
2. 地址栏输入：

   chrome://inspect#remote-debugging

3. 勾选 “Enable remote debugging”
4. 页面显示 Server running at: starting… 即表示就绪

⚠️ 每次重启 Chrome 后都需要重新开启此设置

---

第二步：获取 WebSocket 地址

Chrome 会在用户数据目录生成 DevToolsActivePort 文件，里面包含调试端口和 WebSocket 路径：

文件位置：
%LOCALAPPDATA%\Google\Chrome\User Data\DevToolsActivePort

内容示例：
9222
/devtools/browser/1e19be11-dcf8-4255-9133-f63c7a971911

WebSocket 地址 = ws://127.0.0.1:9222/devtools/browser/1e19be11-xxx

---

第三步：启动 MCP 服务器连接

方式一：通过 WebSocket 直连（推荐）

npx --yes chrome-devtools-mcp@latest --wsEndpoint=ws://127.0.0.1:9222/devtools/browser/xxx

方式二：自动连接（需要 Chrome 已开启远程调试）

npx --yes chrome-devtools-mcp@latest --autoConnect

---

注意事项

⚠️ 不要做的事

错误做法	后果
用 --remote-debugging-port=9222 启动 Chrome	部分 Windows 系统上绑不上端口
用 --user-data-dir 开新配置	失去所有登录态和扩展
用 --browser-url=http://127.0.0.1:9222	Chrome 的 inspect 端口只接受 WebSocket，不接受 HTTP
杀掉 Chrome 进程重开	失去当前浏览会话

✅ 正确做法

• Chrome 正常启动，不加任何额外参数
• 只需在 chrome://inspect#remote-debugging 开启调试
• MCP 连接用 --wsEndpoint 参数，从 DevToolsActivePort 文件获取地址

端口说明

Chrome 的 inspect 远程调试端口特点：

• 端口号写在于 DevToolsActivePort 文件中
• 只接受 WebSocket 连接，不接受 HTTP 请求
• 访问 http://127.0.0.1:9222/json/version 会返回 404

---

可用 MCP 工具

连接成功后可通过 MCP 协议使用以下工具：

导航

• navigate_page — 跳转到 URL
• list_pages — 列出所有标签页
• select_page — 切换标签页
• new_page — 打开新标签页
• close_page — 关闭标签页

操作

• click — 点击元素
• fill — 填写输入框
• fill_form — 填写整个表单
• type_text — 输入文本
• press_key — 按键
• hover — 悬停

调试

• take_screenshot — 截图
• take_snapshot — 获取页面无障碍树
• evaluate_script — 执行 JavaScript
• get_console_message — 获取控制台日志
• list_console_messages — 列出控制台消息

网络

• list_network_requests — 列出网络请求
• get_network_request — 获取网络请求详情

性能

• performance_start_trace — 开始性能录制
• performance_stop_trace — 停止性能录制
• performance_analyze_insight — 分析性能洞察

---

OpenCode 配置

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}

注意：配置后需要重启 OpenCode 才能生效

---

故障排查

MCP 初始化成功但工具调用失败

Error: Failed to fetch browser webSocket URL from http://.../json/version: HTTP Not Found

→ 改用 --wsEndpoint 代替 --browser-url

DevToolsActivePort 文件不存在

→ 打开 chrome://inspect#remote-debugging 开启远程调试

Chrome 提示”正受到自动测试软件控制”

→ 这是正常的，表示 MCP 已连接成功

连接断开

→ 重新打开 chrome://inspect#remote-debugging 获取新的 WebSocket 地址重连