Chrome MCP

# Chrome MCP

把当前这个 Chrome 暴露为通用 MCP server —— 任何支持 MCP 的客户端（Devin、Claude Code、Cursor、ChatGPT、自研 agent…）都连同一个端点，浏览器插件只装一次。

English: Chrome MCP turns your everyday Chrome into a universal MCP server. A small MV3 extension plus a local Node bridge expose http://127.0.0.1:7890/mcp — one Streamable HTTP endpoint that any MCP client can connect to, operating your real tabs, cookies and login sessions. 37 tools: DOM snapshots with element uids, clicking/filling/typing, screenshots, network & console capture, cookies, downloads, PDF export, CDP-powered emulation and performance traces — across iframes, with stale-uid detection and debugger lifecycle management. Docs below are in Chinese; the tool surface and protocol are standard MCP.

架构

MCP 客户端 ── Streamable HTTP ──▶ bridge (node index.js, :7890)
                                      │ WebSocket :7890/ws
                                      ▼
                              Chrome 扩展 (MV3)
                              ├─ chrome.tabs/scripting → 导航/点击/填表/快照/截图（无横幅）
                              └─ chrome.debugger (CDP) → 网络/控制台/模拟/性能/PDF/弹窗

扩展不能接受入站连接，所以必须有一个本地桥进程；桥对客户端暴露标准 MCP，对扩展暴露 WebSocket。

Related MCP server: Real Browser MCP

安装

cd bridge
npm install

1. 启动 bridge

start-bridge.bat        :: 或 bridge\ 下 npm start

环境变量：MCP_PORT（默认 7890）、MCP_CALL_TIMEOUT（默认 120000ms）、 MCP_TOKEN（设了之后 /mcp 要求 Authorization: Bearer）、 MCP_EXT_TOKEN（非扩展来源的 WS 客户端要求 ?token=）。 start-bridge.bat 跑的是 watchdog.mjs 看门狗（崩了自动重启）；开机自启见文末「守护 / 自启」。

2. 加载扩展

chrome://extensions → 打开「开发者模式」→「加载已解压的扩展程序」→ 选 extension/ 目录。 点工具栏图标可看到桥接状态（绿点 = 已连接）。

Chrome 137+ 稳定版已移除 --load-extension 命令行参数，只能手动加载一次（之后自动生效）。

3. 客户端配置（任意 MCP 客户端，统一一个 URL）

工具集（37 个）

• 页面：list_pages, new_page, close_page, select_page, navigate_page, resize_page

• 查看：take_snapshot（uid 来源，覆盖 iframe）, take_screenshot, evaluate_script, extract_text, wait_for（text / textGone / time，跨 frame）

• 交互：click（调试器已附着+前台 tab 时自动走 CDP 可信输入）, click_xy, hover, drag, scroll, fill, fill_form, type_text, press_key, upload_file, handle_dialog

• 会话/数据：get_cookies, set_cookie, remove_cookie, list_downloads, download_file, http_request（带 cookie、免 CORS、支持二进制落盘）, save_pdf

• 调试：list/get_network_request(s), list/get_console_message(s), emulate, performance_start/stop_trace, detach_debugger

工具带 MCP annotations（readOnlyHint / destructiveHint / idempotentHint / openWorldHint），结果同时返回 text + structuredContent。 变更类操作后自动等页面 settle（轮询 load 状态 + 静默窗口）；页面挂着 JS 弹窗时结果里会带 modalDialogs 提醒。

iframe 支持

ensureLib 用 allFrames: true 注入所有 frame（含跨域）。take_snapshot 遍历 frame 树， iframe 内元素 uid 形如 f3xxxxe1（f<frameId> 前缀 + 每文档随机 nonce），交互工具自动路由到对应 frame。

安全

• bridge 只绑 127.0.0.1；HTTP 校验 Host/Origin（防 DNS rebinding——恶意网页无法 POST 到 /mcp）

• WS 只接受 chrome-extension:// 来源，且首个连接的扩展 ID 会被 pin 到 bridge/.extension-id，之后其它扩展一律拒绝；非浏览器来源可用 MCP_EXT_TOKEN 控制

• http_request/download_file 只允许 http(s)（download_file 另允许 data:）——阻止 file:// 读本地文件

• navigate_page 拒绝 javascript:/vbscript:/data: 这类可执行内联内容的 scheme

• filePath 输出有防护：Windows 保留名/ADS 拒绝写入；仓库内已存在文件拒绝覆盖（防止覆写 bridge/扩展源码）

• 拿到这个端点等于拿到浏览器控制权——不要把端口暴露到局域网

• 信任边界说明：/ws 的扩展身份校验能挡住网页和其它扩展（Origin 由浏览器强制），但无法区分本机进程——任何能连 127.0.0.1:7890 的本地进程理论上都能冒充扩展（与 Docker socket、--remote-debugging-port 同一信任模型）。多用户/不可信本机环境请设置 MCP_EXT_TOKEN（非浏览器来源强制 ?token=）并保持 Chrome 锁定。

注意 / 已知边界

• 走 chrome.debugger 的工具会让 Chrome 顶部显示「正在调试此浏览器」横幅。闲置 5 分钟自动 detach；detach_debugger 可手动移除；用户在横幅上点「取消」后该 tab 不再自动重连（导航后解除）。同一 tab 同一时刻只能有一个 debugger（与 DevTools 面板或其它调试扩展互斥），扩展重启留下的僵尸 attach 会自动清扫恢复。

• 调试类收集器与 uid→frame 路由表在页面导航后自动清空；uid 内含每文档随机 nonce，导航后旧 uid 必然报 stale uid/element not found（不会误点新页面上同位置元素）。页面内 DOM 变化后同样建议重拍。

• 合成事件 isTrusted=false；click/press_key 在调试器附着且 tab 前台时自动升级为 CDP Input.* 可信输入（Chrome 不向后台 tab 投递 Input 事件）。

• OOPIF（跨进程跨域 iframe）内的 file 上传和 CDP 网络采集不可达（chrome.debugger 只够到主 target；快照/交互不受此限）。

• evaluate_script 的 args 传元素 uid；多 frame 时用 frameId 或首参数 uid 自动定位 frame。

• 隐身窗口需在 chrome://extensions 手动开「在隐身模式下启用」，new_page isolatedContext 才可用。

• new_page 默认 about:blank 是无 origin 页面，scripting 不可达——先 navigate_page 到真实 URL 再操作。

• evaluate_script 返回值经 JSON 序列化：BigInt→"10n"、循环引用→"[Circular]"、DOM 元素→"<tag>"、函数→"[Function name]"；async 函数会等待 Promise 结果。

• 未实现：Lighthouse 审计、语义搜索（mcp-chrome 的向量检索）、录制回放、OOPIF flat-session CDP——按需再加。

测试

cd bridge
node smoke-test.mjs    :: 协议冒烟：initialize / tools/list / 未接扩展时的报错
node full-test.mjs     :: 端到端 60 项检查（需 Chrome 已加载扩展），覆盖全部 37 个工具

守护 / 自启

bridge 是前台进程，被杀就断。仓库提供两层兜底：

• start-bridge.bat / node bridge/watchdog.mjs —— 看门狗模式：崩溃自动重启（30 秒内 5 连崩会退避 60s），日志写 bridge/bridge-supervisor.log；检测到端口已被占用就自动退出，不会重复起

• 开机自启（免管理员）：powershell -ExecutionPolicy Bypass -File bridge\install-autostart.ps1 —— 在用户启动文件夹放一个隐藏启动项（.lnk → run-hidden.vbs → watchdog.mjs），下次登录自动拉起；卸载删掉那个 .lnk 即可

bridge/adv-tests/ 里是 15 组对抗性测试脚本（协议 fuzz、路径穿越、WS 冒充、竞态、压力等），改安全相关代码后可重跑对应脚本。

CI 在每次 push/PR 自动跑语法检查 + 冒烟测试（.github/workflows/test.yml）。