[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75474":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":29,"discoverSource":30},75474,"cdp-bridge-mcp","Unagi-cq\u002Fcdp-bridge-mcp","Unagi-cq","MCP server that bridges clients to a real browser through CDP and a companion extension.",null,"Python",237,35,1,2,0,15,22,175,45,85.67,"MIT License",false,"main",true,[],"2026-06-12 04:01:18","\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fimages\u002Ficon.png\" alt=\"CDP Bridge MCP Icon\" width=\"120\" height=\"120\" \u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">CDP Bridge MCP\u003C\u002Fh1>\n\n\u003Cdiv align=\"center\">\n\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fcdp-bridge?label=PyPI)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fcdp-bridge\u002F)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-blue)](https:\u002F\u002Fwww.python.org\u002F)\n[![MCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-Browser%20Bridge-green)](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n[![GitHub](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGitHub-Unagi--cq%2Fcdp--bridge--mcp-black)](https:\u002F\u002Fgithub.com\u002FUnagi-cq\u002Fcdp-bridge-mcp)\n\n\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\nCDP Bridge MCP 是一个连接 MCP 客户端与真实浏览器会话的桥接服务。它通过配套的 Chromium 扩展接入浏览器页面，让大模型客户端可以读取标签页、扫描页面、执行 JavaScript、截图、导航和读取 Cookie。\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n中文 | \u003Ca href=\".\u002Fdoc\u002FREADME_EN.md\">English\u003C\u002Fa>\n\u003C\u002Fp>\n\n# 演示视频\n\n| 查询小红书平台 Anthropic 最新动态 | 读取 CSDN 网站作者后台数据分析 |\n| --- | --- |\n| [观看视频](https:\u002F\u002Fwww.bilibili.com\u002Fvideo\u002FBV1RDRQBrEY7\u002F?p=2) | [观看视频](https:\u002F\u002Fwww.bilibili.com\u002Fvideo\u002FBV1RDRQBrEY7\u002F) |\n\n# 项目介绍\n\nCDP Bridge MCP 适合需要让大模型操作真实浏览器的场景。**和无状态 HTTP 抓取不同，它连接的是你已经登录、已经打开的浏览器页面，因此可以复用真实浏览器里的登录态、Cookie、页面状态和前端渲染结果。**\n\n代码仓库：\u003Chttps:\u002F\u002Fgithub.com\u002FUnagi-cq\u002Fcdp-bridge-mcp>\n\n> 本项目使用 Python 编写并发布。MCP 支持 `stdio` 和 `streamable-http` 两种传输模式。\n\n# 项目优势\n\n**为什么用 CDP Bridge MCP，而不是 Playwright MCP、Kimi Bridge 或 Chrome DevTools MCP？**\n\nPlaywright MCP 和 Chrome DevTools MCP 都很强，但它们更偏向“自动化测试 \u002F 调试协议 \u002F 新开浏览器实例”的工作流。Kimi Bridge 的功能权限有限，倾向于通过截图发给视觉模型来完成任务。\n\nCDP Bridge MCP 的目标不同：它更关注让 LLM 或 Agent 产品接管用户正在使用的真实浏览器会话。\n\n- **复用真实登录态**：CDP Bridge MCP 连接的是你已经打开、已经登录的浏览器标签页，可以直接使用现有 Cookie、登录状态、页面上下文和前端渲染结果。很多需要账号态的网站，不需要重新登录或额外搬运 Cookie。\n- **更适合日常浏览器协作**：Playwright 更适合可重复、可脚本化的自动化流程，而 CDP Bridge MCP 更适合 LLM 在用户当前页面上做读取、分析、点击前判断、执行脚本、截图等交互式任务。\n- **页面内容更适合 LLM 消费**：`browser_scan` 会对页面 HTML 做简化，过滤脚本、样式和不可见元素，尽量保留对模型有用的正文、控件和结构信息，减少 token 浪费。\n- **启动链路轻量**：服务端发布到 PyPI 后可直接 `uvx cdp-bridge` 启动，浏览器端加载扩展即可连接，不需要编写 Playwright 脚本，也不需要为每个浏览器实例单独配置调试参数。\n- **适合远端部署和 Agent 产品开发**：如果使用 `streamable-http` 模式，`cdp-bridge` 可以作为一个常驻服务部署在远端服务器上。Agent 后端通过 MCP HTTP 端点连接服务，用户浏览器里的扩展通过 WebSocket 连接同一个服务。这样产品侧不需要托管用户的浏览器，也不需要把账号态搬到云端；用户只要安装扩展并配置 `Bridge Host` 和 `Port`，Agent 就能在用户授权的真实浏览器会话里完成读取、分析和自动化操作。\n- **个人使用和团队产品都能覆盖**：个人用户可以用默认 `stdio + 127.0.0.1:18765` 快速接入本机浏览器；团队或产品开发者可以用 `streamable-http + 远端域名 + WebSocket` 搭建浏览器控制通道，把真实浏览器能力集成进自己的 Agent 产品、客服工作台、数据采集后台或内部自动化系统。\n\n典型部署形态如下：\n\n```text\nAgent 产品 \u002F MCP 客户端  --streamable-http-->  远端 cdp-bridge MCP 服务\n用户浏览器扩展           --WebSocket------->  同一个 cdp-bridge MCP 服务\ncdp-bridge              --chrome.scripting \u002F CDP--> 用户真实浏览器标签页\n```\n\n因此，如果你的目标是“让模型控制一个专门启动的自动化浏览器”，Playwright MCP 很合适；如果你的目标是“调试 Chrome 或精细操作 DevTools 协议”，Chrome DevTools MCP 很合适；如果你的目标是“让模型或 Agent 产品读取和操作用户当前正在使用的真实浏览器页面”，CDP Bridge MCP 更贴近这个场景。\n\n## 系统架构\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdoc\u002Farchitecture.png\" alt=\"CDP Bridge MCP 系统架构图\" \u002F>\n\u003C\u002Fp>\n\n```mermaid\ngraph TB\n    subgraph Client[\"🖥️ MCP 客户端\"]\n        LLM[\"LLM (Claude、Codex 等)\"]\n    end\n\n    subgraph Server[\"⚙️ cdp-bridge MCP 服务 (Python)\"]\n        FastMCP[\"FastMCP\u003Cbr\u002F>stdio \u002F streamable-http\"]\n        TMWD[\"TMWebDriver\u003Cbr\u002F>会话管理器\"]\n        WS[\"Extension WebSocket\u003Cbr\u002F>默认 127.0.0.1:18765\"]\n        HTTP[\"Extension HTTP Fallback\u003Cbr\u002F>默认 127.0.0.1:18766\"]\n        FastMCP --- TMWD\n        TMWD --- WS\n        TMWD --- HTTP\n    end\n\n    subgraph Browser[\"🌐 Chrome \u002F Chromium 浏览器\"]\n        subgraph Extension[\"扩展 (tmwd_cdp_bridge)\"]\n            BG[\"background.js\u003Cbr\u002F>Service Worker\"]\n            CT[\"content.js\u003Cbr\u002F>Content Script\"]\n        end\n        Tabs[\"浏览器标签页\u003Cbr\u002F>(用户真实会话)\"]\n    end\n\n    LLM \u003C-->|\"MCP 协议 (stdio)\"| FastMCP\n    LLM \u003C-->|\"MCP 协议 (streamable-http)\"| FastMCP\n    WS \u003C-->|\"WebSocket (ext_ws)\"| BG\n    HTTP \u003C-->|\"HTTP 长轮询\"| BG\n    BG \u003C-->|\"chrome.scripting\u003Cbr\u002F>CDP Runtime.evaluate\"| Tabs\n    BG \u003C-->|\"chrome.runtime.sendMessage\"| CT\n    CT -->|\"DOM 访问\"| Tabs\n```\n\n**数据流简述：**\n\n1. MCP 客户端通过 **stdio**（子进程）或 **streamable-http**（HTTP 端点）连接 `cdp-bridge` 服务。\n2. TMWebDriver 启动供浏览器扩展连接的 WebSocket（默认 :18765）和内部 HTTP fallback（默认 :18766）。\n3. 浏览器扩展通过 WebSocket 连接服务端，上报所有已打开标签页（`ext_ws` 模式），服务端为每个标签页创建 Session。\n4. 当 MCP 工具被调用（如 `browser_execute_js`），服务端将 JS 代码通过 WebSocket 发送到扩展。\n5. 扩展的 background.js 优先使用 `chrome.scripting.executeScript` 在页面 MAIN world 执行；若页面有 CSP 限制，自动降级为 CDP `Runtime.evaluate`。\n6. 执行结果通过 WebSocket 返回服务端，再由 MCP 协议返回给 LLM 客户端。\n\n## 可用工具\n\nMCP 服务当前暴露以下工具：\n\n| 工具名 | 说明 |\n| --- | --- |\n| `browser_get_tabs` | 获取已连接标签页列表 |\n| `browser_scan` | 扫描当前页面内容，可返回简化 HTML 或纯文本 |\n| `browser_execute_js` | 在当前标签页执行 JavaScript |\n| `browser_switch_tab` | 切换 MCP 活动标签页，不改变用户当前可见的 Chrome 标签页 |\n| `browser_batch` | 批量执行扩展\u002FCDP 命令，适合需要复用 CDP 上下文的复杂操作 |\n| `browser_wait` | 轮询 JavaScript 条件直到返回真值或超时 |\n| `browser_navigate` | 跳转当前标签页到指定 URL |\n| `browser_screenshot` | 获取页面截图 |\n| `browser_cookies` | 读取 Cookie |\n\n# 快速使用\n\n下面是默认配置下最快的使用流程：MCP 使用 `stdio`，浏览器扩展连接本机 WebSocket `127.0.0.1:18765`。\n\n1. 安装 `uv`。\n2. 在 Chrome 或其他 Chromium 浏览器中打开 `chrome:\u002F\u002Fextensions\u002F`，开启“开发者模式”。\n3. 点击“加载已解压的扩展程序”，选择 `src\u002Fcdp_bridge\u002Ftmwd_cdp_bridge` 文件夹。\n4. 在 MCP 客户端里添加 `cdp-bridge`。\n\n以 Codex 为例：\n\n```bash\ncodex mcp add cdp-bridge uvx cdp-bridge@latest\n```\n\n以 Claude Code 为例：\n\n```bash\nclaude mcp add cdp-bridge uvx cdp-bridge@latest\n```\n\n配置完成后，在浏览器里打开任意页面，然后在 MCP 客户端调用 `browser_get_tabs` 或 `browser_scan`。扩展会自动连接 MCP 进程启动的 WebSocket 服务；如果首次看到 `ERR_CONNECTION_REFUSED`，等待几秒自动重连即可。\n\n# 如何使用\n\n## 安装步骤\n\n1. 将项目中提供的浏览器插件 `src\u002Fcdp_bridge\u002Ftmwd_cdp_bridge` 文件夹加载到 Chrome 或其他 Chromium 浏览器。\n2. 在 MCP 客户端配置 CDP Bridge MCP。\n\n然后就可以正常使用了。下面详细介绍上述安装步骤。\n\n> **首次使用**：加载扩展后首次连接 WebSocket 会产生 `ERR_CONNECTION_REFUSED` 报错，这是正常的。扩展内置自动重连机制（每 ~5 秒探测一次），当检测到后端服务启动后会自动恢复连接，无需手动重启扩展。\n\n## 使用流程\n\n1. **加载浏览器扩展**（参考下方步骤）\n2. **配置 MCP 客户端**（参考下方步骤）\n3. **使用任意浏览器工具**（如 `browser_get_tabs`），MCP 服务启动后 WebSocket 服务会自动就绪\n4. 浏览器扩展会在数秒内自动连接，之后即可正常使用所有工具\n\n## 加载浏览器\n\n在 Chrome 或其他 Chromium 浏览器中加载：\n\n1. 打开 `chrome:\u002F\u002Fextensions\u002F`。\n2. 开启“开发者模式”。\n3. 点击“加载已解压的扩展程序”。\n4. 选择 `src\u002Fcdp_bridge\u002Ftmwd_cdp_bridge` 文件夹。\n\n默认情况下，扩展会连接本地 WebSocket 服务 `127.0.0.1:18765`。\n\n扩展弹窗里可以修改连接配置：\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdoc\u002Fplugin.png\" alt=\"CDP Bridge 浏览器插件弹窗\" width=\"360\" \u002F>\n\u003C\u002Fp>\n\n- `Bridge Host`：可填写 `127.0.0.1`、`localhost` 或域名。填写域名时可以不填端口，例如 `bridge.example.com`。\n- `Port`：WebSocket 端口。使用本地默认配置时是 `18765`；如果 MCP 启动时使用了 `--ws-port`，这里需要填同一个端口。域名接入并且服务走默认 WebSocket 端口时，可以留空。\n\n## 配置 MCP\n\n先确认电脑上已安装 `uv`。CDP Bridge MCP 通过 `uvx cdp-bridge@latest` 启动。\n\n### 两种传输模式\n\nCDP Bridge 支持两种 MCP 传输模式，可根据使用场景选择：\n\n| 模式 | 原理 | 适用场景 |\n|------|------|----------|\n| `stdio`（默认） | MCP 客户端以子进程启动服务，通过标准输入\u002F输出通信 | Claude Desktop、Claude Code、Codex 等本地客户端 |\n| `streamable-http` | 服务以独立 HTTP 进程运行，客户端通过 HTTP 请求连接 | 多客户端共享、Docker 部署、服务常驻 |\n\n### 启动参数\n\n| 参数 | 默认值 | 适用模式 | 说明 |\n| --- | --- | --- | --- |\n| `--transport` | `stdio` | 两种模式 | MCP 传输模式。可选 `stdio` 或 `streamable-http`。 |\n| `--ws-port` | `18765` | 两种模式 | 浏览器扩展连接的 WebSocket 端口。无论使用 `stdio` 还是 `streamable-http`，都可以配置。 |\n| `--port` | `8000` | 仅 `streamable-http` | MCP HTTP 服务端口。只在 `--transport streamable-http` 时使用，客户端连接地址是 `http:\u002F\u002F127.0.0.1:\u003Cport>\u002Fmcp`。 |\n\n注意：`--ws-port` 是浏览器扩展连接后端的端口；`--port` 是 MCP 客户端连接后端的 HTTP 端口。两者不是同一个端口。\n\n### 脚本测试\n\n```bash\n# stdio 模式（默认）\nuvx cdp-bridge@latest\n\n# stdio 模式，指定 WebSocket 端口\nuvx cdp-bridge@latest --ws-port 18767\n\n# streamable-http 模式，指定 MCP HTTP 端口\nuvx cdp-bridge@latest --transport streamable-http --port 8000\n\n# streamable-http 模式，同时指定 MCP HTTP 端口和浏览器扩展 WebSocket 端口\nuvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18767\n```\n\n不传 `--transport` 时默认使用 `stdio`。`stdio` 模式没有 MCP HTTP 端口；`streamable-http` 模式的 MCP 服务地址为 `http:\u002F\u002F127.0.0.1:\u003Cport>\u002Fmcp`。\n\n### 标准配置\n\n**stdio 模式：**\n\n```json\n{\n  \"mcpServers\": {\n    \"cdp-bridge\": {\n      \"command\": \"uvx\",\n      \"args\": [\"cdp-bridge@latest\"]\n    }\n  }\n}\n```\n\n如果需要修改浏览器扩展连接的 WebSocket 端口，把 `--ws-port` 加到 `args` 里：\n\n```json\n{\n  \"mcpServers\": {\n    \"cdp-bridge\": {\n      \"command\": \"uvx\",\n      \"args\": [\"cdp-bridge@latest\", \"--ws-port\", \"18767\"]\n    }\n  }\n}\n```\n\n**streamable-http 模式：**\n\n先启动服务：\n```bash\nuvx cdp-bridge@latest --transport streamable-http --port 8000\n```\n\n如果同时要修改浏览器扩展连接的 WebSocket 端口：\n\n```bash\nuvx cdp-bridge@latest --transport streamable-http --port 8000 --ws-port 18767\n```\n\n再配置客户端连接：\n```json\n{\n  \"mcpServers\": {\n    \"cdp-bridge\": {\n      \"type\": \"streamableHttp\",\n      \"url\": \"http:\u002F\u002F127.0.0.1:8000\u002Fmcp\"\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\n# stdio 模式\nclaude mcp add cdp-bridge uvx cdp-bridge@latest\n\n# streamable-http 模式（先启动服务，再注册）\nclaude mcp add cdp-bridge --transport streamable-http http:\u002F\u002F127.0.0.1:8000\u002Fmcp\n```\n\n### Codex\n\n```bash\n# stdio 模式\ncodex mcp add cdp-bridge uvx cdp-bridge@latest\n\n# streamable-http 模式\ncodex mcp add cdp-bridge --transport streamable-http --url http:\u002F\u002F127.0.0.1:8000\u002Fmcp\n```\n\n### opencode\n\n在 `~\u002F.config\u002Fopencode\u002Fopencode.json` 里配置：\n\n**stdio 模式：**\n```json\n{\n  \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n  \"mcp\": {\n    \"cdp-bridge\": {\n      \"type\": \"local\",\n      \"command\": [\n        \"uvx\",\n        \"cdp-bridge@latest\"\n      ],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**streamable-http 模式：**\n```json\n{\n  \"$schema\": \"https:\u002F\u002Fopencode.ai\u002Fconfig.json\",\n  \"mcp\": {\n    \"cdp-bridge\": {\n      \"type\": \"remote\",\n      \"url\": \"http:\u002F\u002F127.0.0.1:8000\u002Fmcp\",\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### OpenClaw\n\n可以使用 OpenClaw CLI 写入 MCP 配置：\n\n```bash\n# stdio 模式\nopenclaw mcp set cdp-bridge '{\"command\":\"uvx\",\"args\":[\"cdp-bridge@latest\"]}'\n\n# streamable-http 模式\nopenclaw mcp set cdp-bridge '{\"type\":\"streamableHttp\",\"url\":\"http:\u002F\u002F127.0.0.1:8000\u002Fmcp\"}'\n```\n\n等价的 stdio 配置结构：\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"cdp-bridge\": {\n        \"command\": \"uvx\",\n        \"args\": [\"cdp-bridge@latest\"]\n      }\n    }\n  }\n}\n```\n\n### 注意事项\n\n- 本项目需要 Python 3.10 或更高版本。\n- 浏览器扩展内置自动重连机制：首次连接失败后会持续探测 WebSocket 服务（每 ~5 秒），当 MCP 服务启动后会自动恢复连接。如果看到 ERR_CONNECTION_REFUSED，等待数秒即可自动恢复。\n- 页面自动化会运行在你的真实浏览器会话中，请只连接你信任的 MCP 客户端。\n\n## 致谢\n\n本项目的浏览器插件和部分代码参考并来源于 [GenericAgent](https:\u002F\u002Fgithub.com\u002Flsdefine\u002FGenericAgent)。感谢原项目作者的开源工作。\n","CDP Bridge MCP 是一个通过 Chrome DevTools Protocol (CDP) 和配套的浏览器扩展将大模型客户端与真实浏览器会话连接起来的服务。其核心功能包括读取标签页、页面扫描、执行 JavaScript 代码、截图、导航及 Cookie 读取，支持 `stdio` 和 `streamable-http` 两种传输模式。该项目特别适用于需要利用现有登录状态和浏览器上下文进行操作的大模型应用场景中，如自动化数据收集、网页内容分析等任务，避免了重新登录或手动管理 Cookie 的麻烦。相比其他解决方案，它更侧重于在用户当前活动的浏览器环境中实现交互式操作，并且能够简化 HTML 内容以提高处理效率。","2026-06-11 03:52:54","CREATED_QUERY"]