cdp-bridge 0.1.7

MCP server that bridges clients to a real browser through CDP and a companion extension.

CDP Bridge MCP

CDP Bridge MCP 是一个连接 MCP 客户端与真实浏览器会话的桥接服务。它通过配套的 Chromium 扩展接入浏览器页面，让大模型客户端可以读取标签页、扫描页面、执行 JavaScript、截图、导航和读取 Cookie。

中文 | English

项目介绍

CDP Bridge MCP 适合需要让大模型操作真实浏览器的场景。和无状态 HTTP 抓取不同，它连接的是你已经登录、已经打开的浏览器页面，因此可以复用真实浏览器里的登录态、Cookie、页面状态和前端渲染结果。

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

本项目以Python语言编写并发布。

为什么用 CDP Bridge MCP ?

为什么用 CDP Bridge MCP 而不是 playwright MCP 或者 chrome devtools MCP ？

Playwright MCP 和 Chrome DevTools MCP 都很强，但它们更偏向“自动化测试 / 调试协议 / 新开浏览器实例”的工作流。CDP Bridge MCP 的目标不同：它更关注让 LLM 直接接管你正在使用的真实浏览器会话。

• 复用真实登录态：CDP Bridge MCP 连接的是你已经打开、已经登录的浏览器标签页，可以直接使用现有 Cookie、登录状态、页面上下文和前端渲染结果。很多需要账号态的网站，不需要重新登录或额外搬运 Cookie。
• 更适合日常浏览器协作：Playwright 更适合可重复、可脚本化的自动化流程，而 CDP Bridge MCP 更适合 LLM 在用户当前页面上做读取、分析、点击前判断、执行脚本、截图等交互式任务。
• 页面内容更适合 LLM 消费：browser_scan 会对页面 HTML 做简化，过滤脚本、样式和不可见元素，尽量保留对模型有用的正文、控件和结构信息，减少 token 浪费。
• 启动链路轻量：服务端发布到 PyPI 后可直接 uvx cdp-bridge 启动，浏览器端加载扩展即可连接，不需要编写 Playwright 脚本，也不需要为每个浏览器实例单独配置调试参数。

如果你的目标是“让模型控制一个专门启动的自动化浏览器”，Playwright MCP 很合适；如果你的目标是“调试 Chrome 或精细操作 DevTools 协议”，Chrome DevTools MCP 很合适；如果你的目标是“让模型读取和操作我当前正在使用的真实浏览器页面”，CDP Bridge MCP 更贴近这个场景。

可用工具

MCP Server 当前暴露以下工具：

工具名	说明
browser_get_tabs	获取已连接标签页列表
browser_scan	扫描当前页面内容，可返回简化 HTML 或纯文本
browser_execute_js	在当前标签页执行 JavaScript
browser_switch_tab	切换活动标签页
browser_navigate	跳转当前标签页到指定 URL
browser_screenshot	获取页面截图
browser_cookies	读取 Cookie
browser_get_sop	读取内置 SOP，支持 tmwebdriver 和 vue3_component。模型遇到 CDP、iframe、截图、Cookie、下载、autofill、文件上传或 Vue3 自定义组件等细节时应按需加载；同一任务中已加载过相关 SOP 时无需重复加载

如何使用

安装步骤

1. 将项目中提供的浏览器插件 src/cdp_bridge/tmwd_cdp_bridge 文件夹加载到 Chrome 或其他 Chromium 浏览器
2. 在MCP客户端配置CDP Bridge MCP

然后就可以正常使用了。下面详细介绍上述安装步骤。

首次使用：加载扩展后首次连接 WebSocket 会产生 ERR_CONNECTION_REFUSED 报错，这是正常的。扩展内置自动重连机制（每 ~5 秒探测一次），当检测到后端服务启动后会自动恢复连接，无需手动重启扩展。

使用流程

1. 加载浏览器扩展（参考下方步骤）
2. 配置 MCP 客户端（参考下方步骤）
3. 使用任意浏览器工具（如 browser_get_tabs），MCP 服务启动后 WebSocket 服务会自动就绪
4. 浏览器扩展会在数秒内自动连接，之后即可正常使用所有工具

加载浏览器

在 Chrome 或其他 Chromium 浏览器中加载：

1. 打开 chrome://extensions/。
2. 开启“开发者模式”。
3. 点击“加载已解压的扩展程序”。
4. 选择 src/cdp_bridge/tmwd_cdp_bridge 文件夹。

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

配置 MCP

第一步，电脑上安装 uv。

脚本测试

uvx cdp-bridge@latest
uv tool run cdp-bridge@latest # uvx不可用时

标准配置

在 MCP 客户端中可以这样配置：

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

Claude Code

claude mcp add cdp-bridge uvx cdp-bridge@latest

Codex

codex mcp add cdp-bridge uvx cdp-bridge@latest

opencode

在~/.config/opencode/opencode.json里面配置：

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

OpenClaw

可以使用 OpenClaw CLI 写入 MCP 配置：

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

等价配置结构如下：

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

注意事项

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

致谢

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

本项目已在 L站 推广，感谢社区。