Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zcode-cdp take over my browser and click the download button on the dashboard"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English | 中文
为 AI Coding Agent 设计的"已登录浏览器接管"框架 —— 让 agent 用真人已登录的 Chrome 干活，配套生产级端口租约 / 看门狗 / 状态机治理。
A logged-in browser takeover framework for AI coding agents (ZCode / Claude Code / Codex …). Drives your real, already-logged-in Chrome via the Chrome DevTools Protocol, with production-grade port lease / watchdog / state-machine governance.
通用浏览器自动化方案（Playwright / Puppeteer / 各 agent 自带的 browser-use）有一个共同前提：起一个全新的、无登录态的浏览器实例，用完即弃。这对"从零打开网页、完成一次性任务"很合适，但对以下场景无能为力：
agent 需要操作你已经登录好的账号（公司后台、已扫码的微信生态、需要短信验证的金融站点、付费订阅内容……）
你不想把账号密码 / 2FA / Cookie 重新喂给一个临时浏览器
多个 agent 会话要并发地各自操控一个 Chrome，且互不抢端口、互不串数据、互不漏资源
Chrome 要能长期存活（durable），跨多个客户端连接复用，而不是每次都冷启动
zcode-cdp 的核心价值一句话：
让 agent 用你已登录好的真人 Chrome 干活，且 N 个 agent 并发时不抢端口、不漏资源。
# | 痛点 | zcode-cdp 怎么解 |
1 | 登录态丢失 —— 通用方案每次起全新浏览器，登录态/2FA/Cookie 全得重来 | 接管真人 Chrome：首次 |
2 | 多 agent 并发抢端口 —— N 个会话同时连 9222 互相踩 | 统一端口租约池（9223–9229 共 7 槽），原子 |
3 | 僵尸 Chrome 吃内存 —— 开 5 个 agent 窗口其中 3 个不碰浏览器，却挂了 3 份 Chrome | 状态机懒加载： |
4 | 孤儿进程烧 CPU —— agent 崩溃后 Chrome/proxy 残留，单核 99% 跑几小时 | 三层看门狗（软 CPU lag / 孤儿超时 / 硬 worker 线程 SIGKILL），扛过两次真实生产事故（见 postmortem） |
5 | 重复提交/发布 —— 网络抖动触发自动重放，导致同一篇文章发两次 | Chrome/backend 异常不自动重放，下次 |
6 | 反爬识别 bot 指纹 —— stealth 插件反而暴露自动化 | 连真 Chrome 指纹本就真，禁 stealth / 禁 |
7 | Python 脚本拿不到登录态 —— Playwright 自启的浏览器和 agent 用的不是同一个 | durable 模式：Python 裸 WebSocket / |
它是怎么做到的：
维度 | 通用方案 (Playwright/Puppeteer/browser-use) | zcode-cdp |
浏览器登录态 | 全新实例，从零登录或注入 Cookie | 接管真人已登录 Chrome（首次 |
启动模型 | agent 一启动就拉起浏览器 | 状态机懒启动：不碰浏览器的窗口 = 0 Chrome 进程 |
并发治理 | 各自为政，易端口冲突 | 统一端口租约池（原子 |
稳定性 | 单层超时 | 三层看门狗（软 / CPU / 硬 worker 线程，扛过 EPIPE 异常风暴） |
生命周期 | 用完即弃 | durable 长期存活 + lazy 按需启动双模式 |
Related MCP server: chrome-dev-mcp
🔑 Take over a real, logged-in Chrome — takeover profile 通过 rsync 从日常 Chrome 继承登录态，之后独立演化；--refresh 可随时强制刷新。
🧠 State-machine lazy proxy — READY_IDLE → RESERVING → STARTING_BROWSER → STARTING_BACKEND → ACTIVE；开 N 个不碰浏览器的窗口 = 0 个 Chrome 进程。
🔒 Port lease & ownership — 统一 mkdir 原子抢锁 + leaseId 校验，防 PID 复用误删新锁；proxy / cdpcc / cdp-takeover 共享同一锁命名空间，杜绝双 owner 竞态。
🐕 Three-layer watchdog — 软看门狗（事件循环延迟）/ CPU 看门狗（主进程 CPU% busy-loop 检测）/ 硬看门狗（独立 worker 线程，60s 无心跳即 SIGKILL，免疫主线程卡死）。
🧰 Three client channels — MCP 工具（mcp__cdp__browser_*）/ 裸 WebSocket / Playwright connect_over_cdp，三种客户端共享同一端口池。
🎭 Per-port profile isolation — 每个端口独立 profile + 不同卡通头像，多账号天然隔离，一眼分清哪个 Chrome 属于哪个会话。
🧹 Exactly-once semantics — 激活期间到达的请求只入队一次；backend generation fencing 防止旧 placeholder 迟到输出污染新 backend。
┌─────────────────────────────────────────────────────────────────────┐
│ Agent Clients (顶层) │
│ │
│ ZCode 会话 Claude Code Python 爬虫 / 自动化脚本 │
│ (MCP stdio) (cdpcc wrapper) (裸 CDP / playwright) │
└─────────┬──────────────────┬──────────────────────┬─────────────────┘
│ │ │
① MCP 工具调用 ① MCP 工具调用 ② 直连 CDP 协议
(JSON-RPC stdio) (JSON-RPC stdio) (WebSocket / connect_over_cdp)
│ │ │
┌─────────▼──────────────────▼──────────────────────│──────────────────┐
│ zcode-cdp-core (中层 / 治理层) │ │
│ │ │
│ ┌──────────────────┐ ┌────────────────────┐ │ │
│ │ zcode-cdp-proxy │ │ cdpcc │ │ │
│ │ (状态机懒加载) │ │ (CC 端口预占) │ │ │
│ │ READY_IDLE→ACTIVE│ │ + cdp-ensure hook │ │ │
│ └────────┬─────────┘ └─────────┬──────────┘ │ │
│ │ │ │ │
│ └───────────┬───────────┘ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ zcode-cdp-lease (统一端口租约 / 所有权) │ │
│ │ 原子 mkdir + leaseId ownership 校验 │ │
│ └─────────────────────┬───────────────────────────┘ │
└───────────────────────────────┼──────────────────────────────────────┘
▼
┌───────────────────────────────────────────────────────────────────────┐
│ N 个已登录 Chrome 实例 (底层 / 端口池) │
│ │
│ 会话临时池 (9223-9229, 最多 7 并发) 脚本固定端口 (93xx, durable) │
│ ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┐ ┌─────┬─────┐ │
│ │9223 │9224 │9225 │9226 │9227 │9228 │9229 │ │9324 │9326 │ │
│ │avatar│avatar│... │ │ │ │ │ │ │ │ │
│ │profile│profile│ │ │ │ │ │ │ │ │ │
│ └─────┴─────┴─────┴─────┴─────┴─────┴─────┘ └─────┴─────┘ │
│ 每端口: 独立 profile (rsync 继承登录态) + 不同头像, 互不串数据 │
└───────────────────────────────────────────────────────────────────────┘
两条路径:
① MCP 工具调用 Agent → proxy/cdpcc → lease 领端口 → 起 Chrome → @playwright/mcp → browser_* 工具
② 直连 CDP 协议 Python/Playwright → cdp-takeover <port> 起 durable Chrome → 直接连 WebSocketNode.js ≥ 18
Chrome（macOS 主力测试，Linux 应该可用）
全局安装 MCP 后端：npm install -g @playwright/mcp
克隆仓库
git clone https://github.com/Lumos-789/zcode-cdp.git
cd zcode-cdp把 bin/ 加入 PATH（或记下绝对路径，下面要用）
# 临时（当前 shell）
export PATH="$PWD/bin:$PATH"
# 永久（写入 ~/.zshrc 或 ~/.bashrc）
echo 'export PATH="/path/to/zcode-cdp/bin:$PATH"' >> ~/.zshrc配置 MCP —— 把下面这段拷进你 agent 客户端的 config.json，把路径改成你的绝对路径：
{
"mcpServers": {
"cdp": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/zcode-cdp/bin/zcode-cdp-proxy.js"]
}
}
}ZCode: 写入 ~/.zcode/cli/config.json
Claude Code: 写入 ~/.claude.json，或项目级 .mcp.json
（Claude Code 用户也可直接用下文的 cdpcc 命令，免去手改配置）
重启 agent —— 现在你的工具列表里多了一批 mcp__cdp__browser_*（navigate / click / type / snapshot / screenshot ……）。
第一次调用 —— 让 agent 调任意 browser_* 工具。proxy 状态机自动流转：
首次会从你日常 Chrome（~/Library/Application Support/Google/Chrome）rsync profile 到该端口目录，继承你已登录的全部账号；
然后启动该端口的 Agent Chrome，挂上 @playwright/mcp，工具调用直达。
之后该端口的 profile 独立演化，不影响你日常 Chrome。
首次
rsync可能需要几十秒（取决于你日常 profile 大小）。后续启动秒级。
模式 | 谁用 | 怎么起 | 生命周期 | 典型场景 |
ZCode lazy proxy | ZCode 会话 | MCP 自动（写好 config 即生效） | 首次调用懒启动； | ZCode agent 日常浏览/操作 |
cdpcc | Claude Code | 命令行 | 启动时预占端口（不起 Chrome），首次调 | 给 Claude Code 一个带浏览器的窗口 |
durable | 人工 / Python 脚本 |
| 跨客户端长期存在，直到手动关 | Playwright |
cdpcc # 自动选空闲端口，启带 cdp 工具的 CC（Chrome 懒起）
cdpcc --resume # 透传给 claude
cdpcc /path/to/project # 在指定目录起 CCcdpcc 启动时只预占端口 + 注入 MCP 配置，不起 Chrome；等你（或 CC）第一次调 mcp__cdp__* 工具时，PreToolUse hook（hooks/cdp-ensure.sh）触发 cdp-takeover 把 Chrome 起到该端口。不用浏览器 = 0 Chrome 进程。
安装 hook：把
hooks/cdp-ensure.sh配成 ZCode/CC 的 PreToolUse hook，matcher 填mcp__cdp__.*。
cdp-takeover # 自动找第一个空闲端口（9223-9229）
cdp-takeover 9324 # 显式端口（建议脚本固定端口走 93xx）
cdp-takeover 9324 --refresh # 强制从源 rsync 该端口 profile（须先关实例）
cdp-takeover status # 打印端口占用表然后 Python 侧：
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp("http://127.0.0.1:9324")
# 用你已登录的真人 Chrome 干活最常见的用法 —— 让 agent 访问一个需要登录的页面，读取数据：
# 在 ZCode / Claude Code 里，对 agent 说：
"打开 https://your-company-dashboard.example.com，把今天的订单数读出来给我。"
# agent 会自动调用：
# 1. mcp__cdp__browser_navigate({ url: "https://your-company-dashboard.example.com" })
# ↑ 首次调用，proxy 状态机自动：
# READY_IDLE → 领端口 9223 → rsync 你日常 Chrome profile（继承登录态）
# → 启动 Agent Chrome → 挂 @playwright/mcp → 工具直达
# 2. mcp__cdp__browser_snapshot() ← 读取页面 ARIA 树
# 3. mcp__cdp__browser_click({ ... }) ← 点开"今日订单" tab（如需要）
# 4. mcp__cdp__browser_take_screenshot() ← 视觉确认
#
# 关键：因为用的是你已登录的 Chrome，不需要你喂账号密码；
# 用完调 browser_close，proxy 释放端口回 READY_IDLE（Chrome 关闭）。进阶：同一台机器上 3 个 agent 会话并发？没问题 —— 每个会话独立 spawn 一个 proxy，各自领不同端口（9223 / 9224 / 9225），互不干扰；其中不碰浏览器的会话 = 0 Chrome 进程。
所有变量都有合理默认值，不设也能跑。需要精细调优时按需覆盖。
变量 | 默认值 | 作用 |
| 自动发现（ | 指向 |
|
| 指向 |
|
| 端口租约锁目录（ |
变量 | 默认值 | 作用 |
|
| 会话临时端口池（ZCode/cdpcc 从中 pick 空闲，进租约） |
|
| 脚本固定端口（durable，不进 pick 池） |
变量 | 默认值 | 作用 |
|
| 孤儿 Chrome（owner 已死、Chrome 还在）超时回收 |
|
| 硬看门狗：worker 线程 N 秒无心跳即 |
|
| 硬看门狗 CPU 检测：主进程 CPU% 超此值视为 busy-loop |
|
| 滑动窗口（ |
|
| 软看门狗：事件循环延迟阈值 |
|
| 软看门狗：连续触发次数 |
|
| 健康检查轮询间隔 |
|
| backend stdout 限流（行/秒） |
|
| backend stderr 限流（段/秒） |
|
| backend stdout 缓冲上限 |
|
| stdin inBuf 上限（防无换行堆积） |
|
| 启动宽限期（lease 判定新锁不算 stale） |
|
| 锁龄超过此值且 owner 已死 → 视为 stale 回收 |
|
|
|
文档 | 内容 |
架构总览 —— 三层组件、状态机流转、端口池与 profile 模型 | |
端口租约模型 —— | |
看门狗事故复盘 ★ —— 两次真实生产事故（ | |
Profile 管理 —— | |
排查清单 —— 端口被占 / Chrome 不起 / 工具不出现 / stale 锁 等常见问题 | |
反爬与编辑器踩坑 —— CDP 三禁令、拟人滚动、Draft.js 注入、风控信号识别 |
CHANGELOG 见 CHANGELOG.md，bug 上报模板见 .github/ISSUE_TEMPLATE/bug-report.md。
macOS：主力测试平台，开箱即用。
Linux：应该可用，但 Chrome profile 源路径需手动调整（默认硬编码 macOS 路径 ~/Library/Application Support/Google/Chrome，Linux 下通常是 ~/.config/google-chrome），lsof / stat 语法差异也已尽量规避。
Windows：未测试，欢迎反馈。
Agent 客户端：支持任何能注册 stdio MCP server 的客户端 —— ZCode、Claude Code、Codex 等。
⚠️ 请务必阅读本节后再使用。
本工具仅用于自动化你有合法权限访问的账号和站点 —— 例如你自己的账号、你有授权的内容管理、CTF / 安全研究、个人数据备份等。
请遵守目标网站的 Terms of Service 和当地法律法规。对滥用本工具进行批量抓取、规避反爬机制、账号滥用等行为，作者不承担任何责任。
takeover 已登录 profile 意味着你的真实登录态会暴露给 agent。请仅在你信任的 agent 环境中使用，避免在不可信的 agent / 第三方脚本中暴露高价值账号。
English | 中文
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
A paid remote MCP for AI agent browser MCP session, built to return verdicts, receipts, usage logs,
A paid remote MCP for AI agent browser DevTools MCP, built to return verdicts, receipts, usage logs,
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Lumos-789/zcode-cdp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server