Browser MCP

将你的 Chrome/Edge 浏览器以 MCP 工具的形式暴露给任何 AI 代理。一个 Chrome 扩展（Manifest V3）本身充当 MCP 服务器：它连接到一个 code-mcp-gateway 并就地应答 MCP 请求——无需本地服务器。它使用与 code-mcp 相同的 JSON-RPC 协议，因此可以无缝接入现有的代理配置。

工作原理

flowchart LR
  subgraph Agent["Agent side"]
    A["MCP client / AI agent"]
  end

  subgraph Gateway["code-mcp-gateway (Cloudflare Worker)"]
    G["wss://code-mcp.tuanm.dev/ws/<id>"]
  end

  subgraph Browser["Your browser"]
    E["Extension (MV3)<br/>service worker = MCP server<br/>offscreen = WS bridge"]
    P["Page (content script)"]
  end

  A -- "MCP JSON-RPC" --> G
  G -- "register / keepalive /<br/>forward requests" --> E
  E -- "CDP / tabs / scripting" --> P

弹窗需要 Device ID 和 Token；扩展直接连接到 网关（注册、每 25 秒保活、75 秒看门狗、带抖动的退避 重连），并就地提供 initialize / tools/list / tools/call 服务。 任何能访问网关的代理都可以驱动浏览器。

可选的本地服务器（browser-mcp.ts）增加了文件存储 （file_read、大文件下载/上传）以及一个普通的本地 MCP HTTP 端点。 参见本地服务器。

快速开始

Chrome 或 Edge >= 111。仅本地服务器或开发工具需要 Bun >= 1.1——扩展可独立运行。

1. 加载扩展。 打开 chrome://extensions，启用开发者 模式，点击加载已解压的扩展程序，然后选择 packages/browser-extension。 （或者运行 bun browser-mcp.ts 并从 http://127.0.0.1:7777/extension 下载 zip 文件。）

2. 连接。 点击工具栏图标（连接后 MCP 标记变为绿色）。输入网关 Device ID 和 Token，点击连接。 弹窗显示 Connected (gateway)。

3. 使用。 将任何 MCP 客户端指向你的网关设备。扩展 以 47 个工具应答 tools/list。

Token 必须与网关上为此设备配置的 Token 一致。网关在每次请求时转发该 Token，扩展会进行验证。如果留空，任何能访问网关的人都可以控制浏览器。

本地服务器

仅当需要文件存储（file_read、大于 512 KB 的下载/上传）或 本地 MCP HTTP 端点时才需要：

bun browser-mcp.ts                  # http://127.0.0.1:7777/mcp
bun browser-mcp.ts --token <s>      # require auth on /mcp + /files

服务器运行后，弹窗也会将 ID + Token 交给服务器自身的 网关链接；没有它扩展仍然可以直接工作。本地客户端使用 http://127.0.0.1:7777/mcp——参见 mcp-client.example.json（如果使用 --token 运行，请添加 "headers": { "Authorization": "Bearer <token>" }）。验证：curl -s http://127.0.0.1:7777/health。

通过 code-mcp-gateway 远程访问

• 直接模式（默认）。 在弹窗中输入 ID + Token；扩展自行提供 MCP 服务。无需本地服务器。

• 服务器端链接。 使用本地服务器时，弹窗连接到 wss://code-mcp.tuanm.dev/ws/<id>，服务器通过 HTTP 应答 MCP。

• CLI（自定义网关）：

  bun browser-mcp.ts --gateway <domain> --token <s> --id <device-id>

  与直接模式使用相同的协议。在网关设备上使用相同的 --token； 切勿在没有 Token 的情况下运行网关模式。设置 BMCP_GATEWAY_DOMAIN 可覆盖 弹窗的默认网关主机。

工具（47 个）

使用 @ref 系统进行元素发现：snapshot 返回带有 [ref=eN] 标记的 交互式元素树；每个交互工具都接受 ref 或 CSS 选择器 （ref 会被缓存并自动解析；过期的 ref 会报错 "run snapshot again"）。

• 发现 — snapshot、find（role/name/text/label/placeholder/ title/testid/selector）、get、is

• 交互 — click、dblclick、type、fill、check、 uncheck、select、hover、focus、press、drag、 scroll、upload

• 导航 — navigate、reload、back、forward、 close、tabs、window

• 页面读取 — extract、execute、screenshot（图像块）、 pdf、wait、highlight

• 状态与调试 — store、cookies、storage、 console、errors、network、status、file_read

• 模拟与控制 — emulate、set（viewport/device/geo/offline/ headers/media）、perms、auth、dialog、frames、touch、 download

Console/errors/network 捕获在首次调用时启动（惰性），因此启用后请 重新加载或导航以捕获流量。Back/forward 使用 CDP 导航历史。 运行 curl -s -X POST http://127.0.0.1:7777/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' 获取完整模式。

标志

安全

• Origin 门控。 /browser/ws 仅接受 chrome-extension:// 来源； /mcp 和 /files/* 拒绝除 localhost 之外的浏览器来源——恶意网站无法通过 localhost 驱动你的浏览器（CSRF）。原生 MCP 客户端（无 Origin 头）不受影响。

• --token 门控 /mcp 和 /files/*（?token= 或 Bearer）； --extension-token 增加一个扩展必须在桥接上提供的密钥。

• 文件 ID 是 12 字符随机十六进制字符串，通过严格模式验证； 上传文件名会被清理。大小限制：上传 500 MiB，截图 8 MiB 内联。

• chrome.debugger 在附加时显示黄色信息栏（同意 信号）；perms/cookies 尽可能使用非 debugger API。

• 默认绑定到 127.0.0.1；在没有 --token 的情况下绑定到 0.0.0.0 会打印警告。

超时

桥接命令：默认 30 秒，navigate/execute/wait_for 为 60 秒，download/file_upload 为 120 秒——本地上限 120 秒，网关模式下上限 55 秒（网关在 60 秒后中止转发）。工具接受 bridge_timeout 进行覆盖。

开发

bun run check   # syntax-check server + scripts + extension JS
bun run test    # mock-extension + mock-gateway E2E suite
bun run build   # rebuild dist/browser-extension.zip
bun browser-mcp.ts  # run the server