browser-bridge

远程 Agent ↔ 本地浏览器桥：Chrome/Edge (MV3) 扩展 + MCP gateway。 你的 Agent 跑在远程机器上，经标准 MCP 操控你本地浏览器：导航、快照、点击输入、截图、执行脚本。

📖 文档站：https://jeffkit.github.io/browser-bridge/（安装 / 配置 / 中转部署 / 使用 / 安全 / FAQ 完整指南）

v0.3+ 能力（当前 0.4.0）：远程 Agent 经标准 MCP 操控本地真实浏览器；多浏览器会话（browserId 路由，/mcp/<浏览器ID> 指定目标）；公网 relay 模式（双方都在 NAT 后时中转，多 token 注册表 + MCP 强制 Bearer）；Firefox 支持（与 Chromium 版同源构建）。

与 web-bridge 呼应成对：web-bridge 注入操控桌面应用 WebView；browser-bridge 操控真实浏览器。协议形状一致（{id, method, params} 请求 / {id, ok, result|error} 应答），@s<gen>:e<N> 元素引用心智相同。

架构

本地机器（可在 NAT 后）                          远程 agent 机器
┌─ Chrome/Edge (≥116) ─────────┐               ┌──────────────────────────┐
│  browser-bridge 扩展          │               │  Agent (recursive/claude- │
│   ├ service worker           │  wss 出站      │  code/codex… 的 MCP 客户端)│
│   │    └ WS 长连接 ━━━━━━━━━━━│━━━━━━━━━━━━━━▶│  browser-bridge-gateway   │
│   ├ content script（按需注入） │               │   ├ WS server（接扩展）     │
│   └ popup / options          │               │   └ MCP server             │
└──────────────────────────────┘               │      ├ streamable HTTP /mcp│
                                               │      └ stdio（同机模式）     │
                                               └──────────────────────────┘

• 扩展只出站连接（浏览器扩展无法监听端口），本地无需开放任何入站端口。

• 唯一前提：本地浏览器能访问 agent 机器上的 gateway 端口（公网 IP / 端口转发 / Tailscale 皆可）。

Related MCP server: chrome-mcp

快速开始

组件跑在哪？ 你的本地机器只装浏览器扩展、不跑任何服务——扩展只发出站连接。gateway 跑在 Agent 所在的远程机器上（下文所有 npx / node 命令都在 Agent 机器执行）；仅当双方都在 NAT 后时，才额外需要一台你的公网 VPS 跑 relay。

1. 起 gateway（在 Agent 机器上）

# npx（推荐）；或 clone 源码后 node packages/gateway/dist/cli.js
npx browser-bridge-gateway@latest serve --token <你的token>
# 或用环境变量：BROWSER_BRIDGE_TOKEN=<token> npx browser-bridge-gateway@latest serve

输出（日志在 stderr）：

gateway 监听 ws://0.0.0.0:17833（/healthz、/mcp）
MCP(streamable HTTP) 端点：http://0.0.0.0:17833/mcp
扩展 options 里填：ws://<本机可达地址>:17833 + 上述 token

2. 装扩展（本地浏览器）

方式 A：从 Releases 下载 browser-bridge-extension-chromium-v*.zip 解压 → chrome://extensions 开发者模式 → 「加载已解压的扩展程序」选解压目录（Firefox 下载 firefox 包后经 about:debugging 临时载入）。

方式 B：源码构建：

git clone git@github.com:jeffkit/browser-bridge.git && cd browser-bridge
pnpm install && pnpm build
# 产物在 packages/extension/dist-extension/（Chromium）与 dist-extension-firefox/（Firefox）

打开扩展「选项」页，填：

• Gateway 地址：ws://<gateway 机器 IP>:17833（有 TLS 时用 wss://）

• Pairing Token：与 gateway --token 一致

保存后扩展立即重连；popup 图标显示连接状态（绿色 = 已连接）。

3. 接入 Agent

远程 agent（streamable HTTP）：

{
  "mcpServers": {
    "browser-bridge": {
      "type": "http",
      "url": "http://<gateway 机器>:17833/mcp"
    }
  }
}

同机 agent（stdio，gateway 由 agent 拉起）：

{
  "mcpServers": {
    "browser-bridge": {
      "command": "npx",
      "args": ["browser-bridge-gateway@latest", "mcp", "--token", "<token>"]
    }
  }
}

MCP 工具面

工具分三档（--permission，默认最窄 read-only）：read-only = status/tab_list/snapshot/screenshot/scroll；navigate-allowlist = 追加 navigate/tab_open/close/select/click/fill/type/press；full = 再追加 evaluate。

推荐流程：browser_snapshot → 读 @s<gen>:e<N> → browser_click/fill/...。引用带快照代次：新快照或页面跳转后旧引用一律 stale_ref（即使元素还在同序号上也不会静默错点），重新快照即可。

安全模型

• token 鉴权：扩展 hello 握手携带，不匹配即断（WS close 4003）。relay 模式支持多浏览器绑定（token 形如 <browserId>=<token>），且 MCP 每请求强制 Authorization: Bearer，槽位与 Bearer 均按此绑定（含离线）。

• 动作面权限档：--permission read-only|navigate-allowlist|full（默认 read-only，最窄）。档位不足返回 permission_denied；非法取值直接启动失败，不静默回退。

• 会话归属（owner）：默认只能读写本会话创建/导航过的标签页，非 owner 的 tabId 返回 tab_not_owned，browser_tab_list 只列 owner（附 hiddenNonOwned 计数）；确需操作既有标签页用 --allow-foreign-tabs。

• 多浏览器会话：扩展以 browserId 标识设备，同一 gateway/relay 可并存多台浏览器；MCP 经 /mcp/<浏览器ID> 绑定目标。同一槽位只有持同一 token 的连接才能顶替。

• 传输加密：gateway 不做 TLS 终结。公网部署请前置 caddy/nginx 提供 wss://，或走 Tailscale 等加密网络；ws:// 仅限可信内网。

• URL 允许列表（可选）：--allow-url <regex>（可多次）既校验 navigate/tab_open 的入参，也下发给扩展做导航兜底——点链接/表单提交/JS 跳转越界会被回退并上报 url_not_allowed（见 browser_status.navBlocked）。缺省不限制；兜底仅作用于 gateway 驱动过的 tab、且仅连接期间生效。

• 页面内容不可信：browser_snapshot 的 text 用 <untrusted-page-content> 界出且结果带 untrusted: true；browser_evaluate 结果同样带 untrusted: true——页面里的「指令」不得当作 Agent 指令。

• 权限：扩展申请 tabs/scripting/storage + <all_urls>（全操控与截图所需，导航兜底复用 tabs），安装时浏览器会提示「读取和更改您在所有网站上的数据」。Firefox 版 host_permissions 为可选权限，需在 about:addons 手动授予。

• 单浏览器会话：新扩展连接顶替旧连接；MCP 调用期间扩展断开会返回 browser_disconnected。

• 两侧需同版本：协议 v3（@s<gen>:e<N> 代次引用）起，旧扩展连新版 gateway 会被 close 4002 拒绝。

验收清单（手工，扩展端）

默认档 read-only 下 browser_tab_open / browser_navigate / browser_click 会被 permission_denied 拒绝——按下面步骤做手工验收时请显式开档： npx browser-bridge-gateway serve --token <t> --permission full --allow-foreign-tabs

1. 加载 dist-extension → options 配置地址 + token → popup 变绿。

2. agent 侧 browser_status → connected: true，并显示当前 permission 档。

3. browser_tab_open 新开 https://example.com → 本地浏览器出现新标签页。

4. browser_navigate 到带图页面 → browser_snapshot 输出含 @s<gen>:e<N> 的文本骨架（外层被 <untrusted-page-content> 包裹）。

5. browser_click 点击某 @s<gen>:e<N> → 页面响应。再拍一次快照后用旧 ref 点击 → 报 stale_ref。

6. browser_screenshot → agent 收到图片。

7. 断开网络 → popup 变灰 → 恢复网络 → 自动重连变绿。

8. 错误 token → 扩展 30s 慢退避；改正后保存 → 立即重连成功。

9. 反向验收：默认档启动（不加 --permission）→ browser_evaluate 返回 permission_denied；--permission navigate-allowlist --allow-url '^https://example\.com/' 下在 example.com 页面点站外链接 → 页面被回退，browser_status.navBlocked 出现记录。

开发

pnpm install
pnpm build            # protocol(tsc) → gateway(tsc) → extension(esbuild)
pnpm test             # gateway 46 项单测/集成测（7 个文件，先 build）
pnpm typecheck        # 三包类型检查
node scripts/smoke.mjs  # 端到端冒烟：gateway serve + 假扩展 + MCP HTTP 全链路
pnpm --filter @browser-bridge/docs dev   # 文档站本地预览（localhost:5173）

文档站部署：push 到 main 且改动 docs/** 时，deploy-docs workflow 自动构建并发到 GitHub Pages。

需要 Chrome ≥ 116（依赖 WS 活动重置 service worker idle timer 的保活语义）。

仓库结构

详见 ARCHITECTURE.md（仓内设计）与 AGENTS.md（AI 协作导航）。