CDP Bridge MCP

CDP Bridge MCP 是一个连接 MCP 客户端与真实浏览器会话的桥接服务，通过配套的 Chromium 插件接入浏览器页面，让任何大模型客户端都可以丝滑、轻易地读取标签页、扫描页面、执行自动化操作、截图和导航。

CDP Bridge MCP 还支持在单台电脑多Profile操作，也支持多用户操作。

代码仓库：https://github.com/Unagi-cq/cdp-bridge-mcp

graph TB subgraph Client["🖥️ MCP 客户端 / Agent"] ClientA["客户端 A<br/>Bearer token_a"] ClientB["客户端 B<br/>Bearer token_b"] end subgraph Server["⚙️ cdp-bridge MCP 服务 (Python)"] FastMCP["FastMCP<br/>stdio / streamable-http"] Middleware["Token Middleware<br/>Authorization Bearer"] TokenManager["TokenManager<br/>按 token 隔离用户上下文"] TMWD["TMWebDriver<br/>会话管理器"] WS["Extension WebSocket<br/>默认 127.0.0.1:18765"] HTTP["Extension HTTP Fallback<br/>默认 127.0.0.1:18766"] FastMCP --- Middleware Middleware --- TokenManager TokenManager --- TMWD TMWD --- WS TMWD --- HTTP end subgraph DeviceA["💻 同一台电脑（多个 Browser Profile）"] ProfileA1["Profile A1<br/>账号 A / token_a"] ProfileA2["Profile A2<br/>账号 B / token_b"] end subgraph DeviceB["🧑‍💻 另一台电脑（另一位用户）"] ProfileB1["Profile B1<br/>账号 C / token_c"] end subgraph BrowserRuntime["🌐 浏览器扩展与页面"] BG["background.js<br/>Service Worker"] CT["content.js<br/>Content Script"] Tabs["浏览器标签页<br/>真实登录态 / 多账号页面"] end ClientA <-->|"MCP 协议\nstreamable-http / stdio"| FastMCP ClientB <-->|"MCP 协议\nstreamable-http"| FastMCP ProfileA1 <-->|"扩展连接\ntoken_a"| WS ProfileA2 <-->|"扩展连接\ntoken_b"| WS ProfileB1 <-->|"扩展连接\ntoken_c"| WS WS <-->|"WebSocket (ext_ws)"| BG HTTP <-->|"HTTP 长轮询"| BG BG <-->|"chrome.scripting<br/>CDP Runtime.evaluate"| Tabs BG <-->|"chrome.runtime.sendMessage"| CT CT -->|"DOM 访问"| Tabs

- MCP 客户端通过stdio（子进程）或streamable-http（HTTP 端点）连接cdp-bridge服务；在streamable-http模式下，客户端可通过Authorization: Bearer <token>指定自己的用户上下文。
- 服务端的Token Middleware负责提取 token，TokenManager负责按 token 隔离会话；同一个 token 下的 MCP 请求和浏览器扩展连接会被路由到同一个上下文。
- TMWebDriver 启动供浏览器扩展连接的 WebSocket（默认 :18765）和内部 HTTP fallback（默认 :18766）；不同电脑上的用户、或同一台电脑上不同 Browser Profile 的扩展，都可以同时接入。
- 每个浏览器扩展在连接时会上报自己的 token 和已打开标签页（ext_ws模式）；服务端据此把不同 profile、不同账号、不同用户的真实浏览器页面隔离开来。
- 当 MCP 工具被调用（如browser_execute_js），服务端只会把 JS 代码发送到当前 token 对应的浏览器会话；扩展的 background.js 优先使用chrome.scripting.executeScript在页面 MAIN world 执行，若页面有 CSP 限制则自动降级为 CDPRuntime.evaluate。
- 执行结果通过 WebSocket 返回服务端，再由 MCP 协议返回给对应客户端；因此可以同时操作同一平台的多个账号，也可以支持多台电脑上的多用户并发使用而互不干扰。
- 安装uv。
- 在 Chrome 或其他 Chromium 浏览器中打开chrome://extensions/，开启“开发者模式”。
- 点击“加载已解压的扩展程序”，选择src/cdp_bridge/tmwd_cdp_bridge文件夹。
- 在 MCP 客户端里添加cdp-bridge。

{ "mcpServers": { "cdp-bridge": { "command": "uvx", "args": ["cdp-bridge@latest"] } } }

配置完成后，在浏览器里打开任意页面，然后在大模型客户端让模型执行网页操作即可。扩展会自动连接 MCP 进程启动的 WebSocket 服务；如果首次看到ERR_CONNECTION_REFUSED，等待几秒自动重连即可。
- 将项目中提供的浏览器插件src/cdp_bridge/tmwd_cdp_bridge文件夹加载到 Chrome 或其他 Chromium 浏览器。
- 在 MCP 客户端配置 CDP Bridge MCP。

首次使用：加载扩展后首次连接 WebSocket 会产生ERR_CONNECTION_REFUSED报错，这是正常的。扩展内置自动重连机制（每 ~5 秒探测一次），当检测到后端服务启动后会自动恢复连接，无需手动重启扩展。
- 加载浏览器扩展（参考下方步骤）
- 配置 MCP 客户端（参考下方步骤）
- 使用任意浏览器工具（如browser_get_tabs），MCP 服务启动后 WebSocket 服务会自动就绪
- 浏览器扩展会在数秒内自动连接，之后即可正常使用所有工具
- 打开chrome://extensions/。
- 开启“开发者模式”。
- 点击“加载已解压的扩展程序”。
- 选择src/cdp_bridge/tmwd_cdp_bridge文件夹。

默认情况下，扩展会连接本地 WebSocket 服务127.0.0.1:18765。

- Bridge Host：可填写127.0.0.1、localhost或域名。填写域名时可以不填端口，例如bridge.example.com。
- Port：WebSocket 端口。使用本地默认配置时是18765；如果 MCP 启动时使用了--ws-port，这里需要填同一个端口。域名接入并且服务走默认 WebSocket 端口时，可以留空。
- Token：streamable-http多用户模式下用于把浏览器扩展和 MCP 客户端绑定到同一个用户上下文。留空时扩展会自动写入默认值__default__。如果你使用 Bearer token 访问远端 MCP 服务，这里必须填写和客户端完全一致的 token。

先确认电脑上已安装uv。CDP Bridge MCP 通过uvx cdp-bridge@latest启动。

注意：--ws-port是浏览器扩展连接后端的端口；--port是 MCP 客户端连接后端的 HTTP 端口。两者不是同一个端口。

# stdio 模式（默认） uvx cdp-bridge@latest # stdio 模式，指定 WebSocket 端口 uvx cdp-bridge@latest --ws-port 18767 # streamable-http 模式，指定 MCP HTTP 端口 uvx cdp-bridge@latest --transport streamable-http --port 8000 # streamable-http 模式，同时指定 MCP HTTP 端口和浏览器扩展 WebSocket 端口 uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18767 # streamable-http 模式，只允许指定 token 接入 uvx cdp-bridge@latest --transport streamable-http --port 8000 --tokens "team_alice,team_bob" # streamable-http 模式，同时指定 MCP HTTP 端口和监听的ip，远程机器可通过172.25.240.1:8000访问运行的MCP Server uvx cdp-bridge@latest --transport streamable-http --host 172.25.240.1 --port 8000 # 也可以通过环境变量传入 token 白名单 CDP_BRIDGE_TOKENS="team_alice,team_bob" uvx cdp-bridge@latest --transport streamable-http --port 8000

不传--transport时默认使用stdio。stdio模式没有 MCP HTTP 端口；streamable-http模式的 MCP 服务地址为http://127.0.0.1:<port>/mcp。

V3 修正了 V2 “只要模型返回非空文本就算成功”的统计问题，改用场景级验收规则，并把场景分为确定性核心对比、真实登录态诊断和标签页诊断。核心对比会记录通过率、质量、工具成功率、API 轮次、Token 和耗时，同时生成 Markdown 报告与结构化 JSON。默认测试当前工作区源码，并固定 Playwright MCP 版本，避免latest漂移。

export ANTHROPIC_API_KEY="你的 API Key" export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" # 可选 export ANTHROPIC_MODEL="deepseek-v4-pro" # 可选 # 只做前置检查和本地构建，不调用 LLM uv run python reports/V-003-2026-08-09/eval_mcp_compare_v3.py --preflight --build-check # 核心对比，默认每个场景重复 3 次 uv run python reports/V-003-2026-08-09/eval_mcp_compare_v3.py --repeats 3 # 加入真实登录态和标签页诊断场景 uv run python reports/V-003-2026-08-09/eval_mcp_compare_v3.py --suite all --repeats 3

查看V3 测试报告和V3 测评脚本。脚本运行时还会在同一目录生成eval_results.json；默认不保存完整工具正文，避免把真实标签页或页面隐私写入结果，确需审计时可增加--save-tool-output。

脚本位置：reports/V-002-2026-07-12/eval_mcp_compare_v2.py。运行完整测评前，需要准备浏览器扩展、CDP Bridge 服务、Playwright MCP、Anthropic 兼容 API，以及ANTHROPIC_API_KEY：

export ANTHROPIC_API_KEY="你的 API Key" export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" # 可选 export ANTHROPIC_MODEL="deepseek-v4-pro" # 可选 # 默认 3 个场景，每个场景重复 3 次 python reports/V-002-2026-07-12/eval_mcp_compare_v2.py # 只测某个场景，或只测一侧 python reports/V-002-2026-07-12/eval_mcp_compare_v2.py --case numpy --repeats 3 python reports/V-002-2026-07-12/eval_mcp_compare_v2.py --cdp-only # 只检查依赖并生成报告，不调用 LLM python reports/V-002-2026-07-12/eval_mcp_compare_v2.py --preflight

报告会写入reports/V-002-2026-07-12/eval_compare_report.md。V2 的示例运行结果（2026-07-12、每个场景 1 次）如下，数值仅用于说明该次环境下的观测，不代表所有网络、浏览器登录态或模型配置：

{ "mcpServers": { "cdp-bridge": { "command": "uvx", "args": ["cdp-bridge@latest"] } } }

如果需要修改浏览器扩展连接的 WebSocket 端口，把--ws-port加到args里：

{ "mcpServers": { "cdp-bridge": { "command": "uvx", "args": ["cdp-bridge@latest", "--ws-port", "18767"] } } }

uvx cdp-bridge@latest --transport streamable-http --port 8000

uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18767

{ "mcpServers": { "cdp-bridge": { "type": "streamableHttp", "url": "http://127.0.0.1:8000/mcp" } } }

{ "mcpServers": { "cdp-bridge": { "type": "streamableHttp", "url": "http://127.0.0.1:8000/mcp", "headers": { "Authorization": "Bearer team_alice" } } } }

# stdio 模式 claude mcp add cdp-bridge uvx cdp-bridge@latest # streamable-http 模式（先启动服务，再注册） claude mcp add cdp-bridge --transport streamable-http http://127.0.0.1:8000/mcp

{ "mcpServers": { "cdp-bridge": { "type": "http", "url": "http://127.0.0.1:8000/mcp" } } }

注意：使用配置文件方式时，需要先启动cdp-bridge服务（uvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18765），然后重启 Claude Code。

# stdio 模式 codex mcp add cdp-bridge uvx cdp-bridge@latest # streamable-http 模式 codex mcp add cdp-bridge --transport streamable-http --url http://127.0.0.1:8000/mcp

{ "$schema": "https://opencode.ai/config.json", "mcp": { "cdp-bridge": { "type": "local", "command": [ "uvx", "cdp-bridge@latest" ], "enabled": true } } }

{ "$schema": "https://opencode.ai/config.json", "mcp": { "cdp-bridge": { "type": "remote", "url": "http://127.0.0.1:8000/mcp", "enabled": true } } }

# stdio 模式 openclaw mcp set cdp-bridge '{"command":"uvx","args":["cdp-bridge@latest"]}' # streamable-http 模式 openclaw mcp set cdp-bridge '{"transport":"streamable-http","url":"http://remoteip:8000/mcp"}'

{ "mcp": { "servers": { "cdp-bridge": { "command": "uvx", "args": ["cdp-bridge@latest"] } } } }

- 本项目需要 Python 3.10 或更高版本。
- 浏览器扩展内置自动重连机制：首次连接失败后会持续探测 WebSocket 服务（每 ~5 秒），当 MCP 服务启动后会自动恢复连接。如果看到 ERR_CONNECTION_REFUSED，等待数秒即可自动恢复。
- 页面自动化会运行在你的真实浏览器会话中，请只连接你信任的 MCP 客户端。

本项目的浏览器插件和部分代码参考并来源于GenericAgent。感谢原项目作者的开源工作。

Real-time web data, structured for agents