Chrome 浏览器 MCP

一个本地桥接器，让私有的 ChatGPT 开发者模式应用能够检查并控制你桌面版 Google Chrome 中已打开的标签页。

当前补丁版本：0.1.2。每个补丁都必须提升此版本号；CI 会拒绝未提升版本号的补丁。

该桥接器暴露 17 个 MCP 工具：

• 读取类：browser_status、list_tabs、get_active_tab、read_tab、read_tabs、search_tabs

• 操作类：click、type、fill_form、press_key、scroll、select_option、navigate、new_tab、close_tab

• ChatGPT 子代理：spawn_chatgpt_agent、read_chatgpt_agent

spawn_chatgpt_agent 默认在后台打开一个新的 chatgpt.com 标签页，提交用户提供的提示词原文，并返回其标签页 ID。read_chatgpt_agent 通过与普通标签页相同的受限语义提取器读取该子标签页；如果子代理仍在生成内容，可稍后再次调用。

操作目标接受 CSS 选择器或精确的可见文本 / aria-label / placeholder / name / 关联标签文本。目标不明确时直接失败，不做猜测。

该桥接器不暴露 cookies、本地存储、会话存储、已保存密码、隐藏输入值、任意 JavaScript 执行、Chrome 内部页面或隐身标签页。它不使用 Chrome 调试器 API。

已验证的路径

端到端测试会启动一个真实的 Chromium 进程，加载未打包的 Manifest V3 扩展，启动真实的原生消息宿主，通过 Streamable HTTP 连接 MCP 客户端，打开真实页面，列出并读取它们，并验证密码输入值不会被返回。单元/集成测试覆盖了页面操作、MCP 路由、ChatGPT 子代理工具的注册/组合、生成的扩展版本同步，以及 Chrome/原生消息使用的运行时文件是否被 Git 跟踪。

MCP client
  -> http://127.0.0.1:2091/mcp
  -> native host process
  -> Chrome Native Messaging
  -> MV3 extension
  -> live Chrome tabs

运行所有门禁：

npm ci
npm run check

Related MCP server: sansan-chrome-mcp

架构

ChatGPT developer-mode app
          |
          | OpenAI Secure MCP Tunnel (outbound HTTPS)
          v
127.0.0.1:2091/mcp
          |
          | same local Node process
          v
Chrome Native Messaging host
          |
          v
Chrome MV3 extension
          |
          +-- chrome.tabs
          +-- chrome.scripting (isolated-world reads + actions)

当扩展连接时，Chrome 启动原生宿主。原生宿主启动回环 MCP 端点。因此，只要 ChatGPT 使用该应用，Chrome 就必须保持打开且扩展必须处于启用状态。

要求

• macOS

• Google Chrome 120+

• Node.js 20+

• 一个启用了开发者模式的 ChatGPT 账户

• 一个 OpenAI Platform 隧道 ID 和具有 Tunnels Read + Use 权限的运行时 API 密钥

• tunnel-client

1. 安装原生宿主并加载扩展（仅一次）

npm run install:mac

这会将原生宿主清单安装到：

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.komaksym.chrome_browser_mcp.json

然后：

1. 打开 chrome://extensions。

2. 启用开发者模式。

3. 点击加载已解压的扩展程序。

4. 选择本仓库的 dist/extension 目录。

5. 确认扩展 ID 完全一致：

jlpddlfiallighiohmhhkemgbhofpnha

如果 ID 不同，请勿继续。原生宿主只接受该精确的扩展来源。

2. 更新后续补丁

你只需选择一次扩展目录。 dist/ 下构建好的扩展和 MCP 桥接器已提交到 Git，CI 会拒绝源码变更但已提交的运行时构建过时的补丁。

对于之后的每个补丁，正常的更新流程完全如下：

git pull

然后打开 chrome://extensions 并点击更新。不要再次选择扩展路径，也不要为了消费已发布的补丁而单独运行构建命令。

git pull 会同时更新 dist/extension（Chrome 加载的内容）和 dist/bridge（原生宿主执行的内容）。点击更新会重新加载已解压的扩展/原生消息连接，从而使用新拉取的运行时。

可见的扩展版本必须在每个补丁中变化。本补丁必须显示 0.1.2。如果仍显示旧版本，说明拉取的运行时未被应用。

3. 验证本地浏览器链路

保持 Chrome 打开，然后运行：

npm run verify:local

成功检查会打印：

• 扩展 ID；

• 扩展版本；

• MCP 服务器版本；

• 17 个已公布的 MCP 工具。

如果扩展和 MCP 版本不一致，或者桥接器过旧而无法报告其 MCP 版本，验证器将失败。这使得过时的 15 工具桥接器能立即与过时的 Chrome 扩展区分开来。

4. 配置 Secure MCP Tunnel

在 OpenAI Platform 中创建隧道和运行时 API 密钥。然后：

export CONTROL_PLANE_API_KEY="sk-..."
./scripts/configure-tunnel.sh tunnel_0123456789abcdef0123456789abcdef

tunnel-client doctor --profile chrome-browser-mcp --explain
tunnel-client run --profile chrome-browser-mcp

该配置文件将隧道转发到：

http://127.0.0.1:2091/mcp

只要 ChatGPT 需要浏览器工具，就保持 tunnel-client run 处于活动状态。

5. 添加到 ChatGPT

1. 在 ChatGPT 中，启用设置 -> 安全与登录 -> 开发者模式。

2. 打开设置 -> 插件。

3. 点击 + 创建开发者模式应用。

4. 选择隧道作为连接类型。

5. 选择或粘贴隧道 ID。

6. 使用 app-metadata.json 中的元数据。

7. 确认 ChatGPT 发现全部 17 个工具。

8. 在新聊天中，点击 + -> 更多，选择 Chrome 浏览器，然后提问：列出我打开的 Chrome 标签页。

精确的验证和故障排除步骤请参阅 docs/CHATGPT_SETUP.md。

安全模型

网页文本是数据，绝不是权威。每个内容结果都包含一个明确的不可信内容标记，工具指令会告诉模型永远不要将页面中找到的指令转化为操作。

扩展有意请求访问所有 HTTP 和 HTTPS 页面，以便读取和交互普通的已打开标签页。保护边界是：

• 扩展由你在本地加载；

• Chrome 只启动精确列入白名单的原生宿主；

• 原生宿主拒绝除稳定扩展 ID 之外的任何来源；

• MCP 端点仅绑定到 127.0.0.1；

• 隧道仅支持出站连接；

• 操作仅限于普通 HTTP(S) 标签页，不暴露任意 JavaScript、调试器访问、cookies 或浏览器存储；

• 不明确的人类可读目标会被拒绝而不是猜测。

在无人值守使用之前，请阅读 THREAT_MODEL.md 和 SECURITY_REVIEW.md。

已知限制

• 一次应只有一个 Chrome 配置文件加载该扩展；两个配置文件可能争用端口 2091。

• Chrome 内部页面、Chrome 网上应用店页面、file:// 页面和隐身标签页无法被读取或控制。

• 不遍历跨源 iframe。

• 纯 Canvas 应用和 Chrome 内置 PDF 查看器可能返回很少的语义文本。

• 提取器返回主文档的可见文本、标题、链接和描述，而非原始 HTML。URL 中的凭据和片段会被移除，敏感查询参数会被脱敏。

• press_key 使用 DOM 键盘事件；Enter 和 Escape 有明确的常见情况行为，但某些网站需要受信任的 OS/CDP 键盘输入。

• ChatGPT 子代理提交依赖于 ChatGPT 当前的 Web 编辑器（#prompt-textarea）和发送按钮标记；未来 ChatGPT UI 的变更可能需要更新这些选择器。

• read_chatgpt_agent 返回子标签页的可见语义页面文本，而非特权 ChatGPT API 响应。

• 文件上传有意未实现，因为通用地实现它需要更强大的文件系统/调试器接口。

开发

npm ci
npm run version:check
npm run typecheck
npm run lint
npm test
npm run artifacts:check
npm run test:e2e
npm audit