de en es ja ko ru zh

browser-bridge

Name: browser-bridge
Author: weaming

by weaming

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Browser Bridge

AI ↔ 浏览器控制桥:把浏览器变成 MCP 工具集。任何 MCP 客户端(AI 程序)通过标准 MCP 协议调用 browser_snapshot / browser_click / browser_type 等工具,在真实浏览器里操作网页。

支持任意 MCP 客户端:Claude、codex、自定义 agent、curl
默认跟随模式:AI 自动控制你当前激活的标签页,零配置
真实浏览器,非 headless:登录态、验证码(提示你手动)、反爬特征自然

快速开始

1. 下载

从 Releases 下载一个压缩包:

browser-bridge-<platform>-<arch>.zip — 按你机器的平台选

解压到任意目录(下文用 <DIR> 表示),目录内含 browser-bridge/(扩展)、browser-bridge-host、install-host.sh(Windows 为 install-host.ps1)。

2. 加载扩展

打开 chrome://extensions
右上角打开开发者模式
点「加载已解压的扩展程序」,选择解压后的 browser-bridge/ 目录

3. 安装 host

macOS / Linux:

cd <DIR>
./install-host.sh         # Windows(PowerShell): .\install-host.ps1

运行后会列出检测到的浏览器,回车安装到全部,或输入序号选特定浏览器;也支持参数直接指定:

./install-host.sh --all      # 安装到全部浏览器
./install-host.sh --chrome   # 只装 Chrome(--chromium / --edge 同理)

扩展 ID 已内置固定,无需手动填写;若你的扩展 ID 不同,可追加传参:./install-host.sh <你的扩展ID>。

若浏览器已打开,安装后请完全退出并重启浏览器。

4. 使用

任意 MCP 客户端连接:

MCP server: http://127.0.0.1:1234/mcp

端口被占时自动 +1,实际端口看扩展 popup(已连接 · MCP端口 xxxx)或 ~/.browser-bridge/port。

codex 配置示例(~/.codex/config.toml):

[mcp_servers.browser]
url = "http://127.0.0.1:1234/mcp"

之后告诉 AI「帮我看看这个页面…」即可。

Related MCP server: Playwright MCP Server

MCP 工具

工具	参数	说明
`browser_control_status`	—	查询控制目标与连接状态
`browser_list_tabs`	—	列出所有标签页
`browser_use_tab`	`tabId`(-1 回跟随)	固定/切换控制目标
`browser_new_tab`	`url?`	新建标签页并立即跳转(缺省空白页)
`browser_close_tab`	`tabId?`	关闭标签页(缺省关受控页,自动回跟随)
`browser_activate_tab`	`tabId`	激活标签页给用户看,不改控制目标
`browser_duplicate_tab`	`tabId?`	复制标签页(缺省复制受控页)
`browser_pin_tab`	`tabId?`, `pinned?`	固定/取消固定标签页
`browser_snapshot`	—	可交互元素快照(ref 编号+坐标)
`browser_extract`	`format?`(markdown\|html\|raw)	提取正文;对话页(ChatGPT/Gemini)按问答轮次组装;format=html 返回净化 HTML,raw 返回原始 body HTML
`browser_screenshot`	—	可视区截图(dataUrl,视觉理解复杂布局)
`browser_url`	—	查询当前控制页 URL 与标题(轻量)
`browser_click`	`ref`, `button?`	点击
`browser_dblclick`	`ref`	双击
`browser_type`	`ref`, `text`, `clear?`	输入(兼容 React 受控输入)
`browser_form_fill`	`fields[]`	批量填写多个字段
`browser_press` / `browser_key`	`key`, `modifiers?`	按键(支持 ctrl/shift/alt/meta)
`browser_select`	`ref`, `value`	下拉框
`browser_scroll`	`dir`, `amount?`, `ref?`	滚动
`browser_hover`	`ref`	悬停
`browser_highlight`	`ref`	高亮元素 1s(用户可见 AI 操作位置)
`browser_drag`	`fromRef`, `toRef`	HTML5 拖拽
`browser_goto`	`url`	跳转到指定 URL
`browser_back`	—	浏览器后退
`browser_refresh`	—	刷新页面
`browser_wait_for`	`ms` 或 `selector` 或 `text`(三选一,不可组合)	等待:定时(ms≤60s),或等元素出现,或等页面文本出现(UI 条件最多 5s)
`browser_eval`	`code`, `world?`(main\|isolated), `await?`, `timeout_ms?`	在页面执行 JS(默认 main=真实页面上下文,可读 localStorage/页面变量、改 DOM);结果 JSON 化返回,循环引用/函数/DOM 都能安全序列化
`browser_network`	`op?`(list\|install\|clear), `filter?`, `limit?`, `include_body?`, `redact?`, `since_id?`	查看页面真实网络请求。`install` 装一次钩子后,fetch/XHR 全部记录(含流式 SSE 响应体);默认对 authorization/cookie/api-key 等 header 打码
`browser_webmcp_list`	—	探测当前页面经 WebMCP(`document.modelContext`,W3C webmcp)注册的工具:名称/描述/参数 JSON Schema/annotations。按需注入只读脚本快照一次,不注册、不留监听器;页面未暴露 API(需 Chrome 146+ 开启 WebMCP)时返回 `supported:false`
`browser_webmcp_call`	`name`, `args?`, `timeout_ms?`	调用页面注册的 WebMCP 工具,返回字符串化执行结果;先 `browser_webmcp_list` 拿 name 与 inputSchema
`browser_reload_extension`	—	重载扩展使磁盘上的新代码生效(改完扩展文件后用,≤30s 自动重连)

AI 自行编排:snapshot → 决策 → 操作 → 再 snapshot,直到任务完成。

browser_eval / browser_network 用法

前者用于读页面内部状态(如登录 token、前端 store)、调页面函数、临时改样式;后者用于观察接口协议:

# 1. 装钩子(一次即可,页面 reload 后需重装)
browser_network(op="install")
# 2. 照常操作页面(点击/输入/或 browser_eval 里自己发 fetch)
# 3. 看刚才发了什么
browser_network(op="list", filter="completion", include_body=true)

限制:钩子在页面 reload 后丢失(需重装);只覆盖 fetch 与 XMLHttpRequest(WebSocket/EventSource 不抓);响应体用 clone() 旁路读取,封顶 200KB/条、300 条。

控制模式

跟随模式(默认):控制你当前激活的标签页,切 tab 即切目标
固定模式:锁定某个标签页(切换不跟随);popup 一键固定/取消,或 AI 调 browser_use_tab

工具栏图标徽标:无 = 跟随中;AI 琥珀 = 已固定;! 红 = 连接异常。

架构

任意 MCP 客户端
   │ MCP (Streamable HTTP, 127.0.0.1:1234/mcp)
browser-bridge host(单进程 = MCP ↔ 帧协议翻译器)
   │ native messaging(stdin/stdout 帧)
Chrome 扩展
   ├─ background:转发、目标解析、保活、状态徽标
   └─ content script:快照 / 执行

MV3 扩展无法监听端口,native host 是唯一通道(Chrome 官方 DevTools MCP 同构)。

从源码构建(开发者)

需要 bun。日常开发用 make:

make            # = make deploy:构建 host + 扩展,并 rsync 到 Chrome 加载目录
make setup      # 首次安装:deploy + 注册 native host
make build      # 只构建:dist/browser-bridge-host + extension-dist/
make host       # 只注册 native host(HOST_TARGET=--chromium/--edge/--all 可指定)
make test       # bun test(含 mock 模式 MCP API 集成测试)
make typecheck  # tsc --noEmit
make pack       # 交叉编译 5 平台发布包 dist/release/*.zip
make reload     # 让扩展重载、加载磁盘上的新代码
make status     # 查看 host 的 MCP 端口

EXT_DIR 默认 ~/chrome/browser-bridge(即 chrome://extensions 里加载的那个目录),可用 make deploy EXT_DIR=... 覆盖。

生效方式:扩展是 unpacked 加载,但 Chrome 不会因为文件变化自动重载它 —— service worker 被扩展内的 30s 保活 alarm 长期托住,旧代码会一直活着。正确姿势:make deploy 之后跑 make reload(调 browser_reload_extension 工具触发 chrome.runtime.reload()),或手动在 chrome://extensions 点一次「重新加载」。重载后扩展会在 ≤30s 内重连 host,Chrome 会用新编译的 host 二进制重新拉起进程。

手动构建(等价):

bun run build                    # 当前平台 host + 扩展
./scripts/install-host.sh        # 注册 host(默认内置扩展 ID)
bun run scripts/build.ts --all   # 交叉编译全部平台 + 发布包(发布用)
bun test                         # 单元 + MCP API 集成测试(无需浏览器)

配置

BROWSER_BRIDGE_PORT:MCP 初始端口(默认 1234,被占自动 +1)
BROWSER_BRIDGE_MOCK=1:模拟扩展应答(开发测试用)

故障排查

现象	原因	解决
popup 显示「host 未连接」	未安装 host / 浏览器未重启	运行 install-host,完全退出浏览器重开
`Invalid native messaging host name`	host 名含连字符(旧版本)	更新到新版(host 名 `com.browserbridge`)
扩展 ID 不匹配	用旧版 manifest 加载	重新下载扩展,或 install-host 传参 `install-host.sh <你的ID>`
MCP 连不上	host 未运行	先打开浏览器+扩展(host 由 Chrome 拉起)
目标标签页不可达	页面未就绪/不是 http(s)	等页面加载,或用 `browser_use_tab` 固定

License

MIT

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

sncro A
io.github.scottconfusedgorilla
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser Automation Developer Tools Monitoring
2
Aginx Browser A
net.aginx
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Browser Automation Agent Orchestration
138
Hyperbrowser A
io.github.pipeworx-io
Hyperbrowser MCP — wraps the Hyperbrowser AI-agent browsing API
Browser Automation Agent Orchestration
391
browser-mcp
io.github.Shreyas-Profile
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Browser Automation Web Scraping
2

Related MCP Servers

BrowserPilot
Browser Automation Web Scraping
soulxyz
F
license
B
quality
D
maintenance
Enables AI to control browsers via natural language for web automation, testing, and data scraping. Supports Chrome-based browsers and integrates with any MCP-compatible AI tool.
Updated a year ago (2025-10-05 03:12 UTC)
17
2
-
Playwright MCP Server
Browser Automation Testing & QA Tools
muhammadraheel-vd
F
license
Not graded
quality
D
maintenance
Enables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.
Updated 4 months ago (2026-06-22 05:51 UTC)
-
Browser Controller
Browser Automation Agent Orchestration
compnew2006
A
license
Not graded
quality
B
maintenance
Gives MCP-compatible AI agents direct control of your real browser with existing sessions, logins, and cookies. Supports multiple agents concurrently with tab targeting.
Updated 2 days ago (2026-10-10 03:57 UTC)
3 npm
8
MIT
Chrome MCP Bridge
Browser Automation Web Scraping
randyrt
F
license
Not graded
quality
C
maintenance
Enables AI assistants to control and interact with a Chrome browser via MCP, providing tools for navigation, screenshots, clicking, form filling, content extraction, and tab management.
Updated 2 months ago (2026-08-10 06:47 UTC)
-