Zendriver MCP

zendriver-mcp

通过 MCP 为 LLM Agent 提供难以检测的浏览器自动化。

zendriver-mcp 是一款 MCP 服务，为你的编码 Agent（Claude、Cursor、Gemini、Copilot）提供一个真正可用的 Chrome 浏览器，让它能访问真实网页——包括 Cloudflare 防护的网站、有登录墙的页面，以及会检测并拦截 WebDriver 的页面。

它基于 Zendriver 构建，直接使用 Chrome DevTools Protocol，而不是通过 WebDriver。这意味着没有 navigator.webdriver 标志，没有无头浏览器特征，而且指纹看起来就像普通的 Chrome 安装。

在此基础上，zendriver-mcp 集成了 Agent 完成工作所需的一切：节省 Token 的 DOM 遍历器、带稳定 uid 的无障碍树、性能跟踪、Lighthouse 审计、堆快照、拟人化输入、设备模拟、Cookie 往返传递等——22 个模块，共 96 个工具。

亮点

• 从设计上就难以检测。 Zendriver 保持干净的指纹；我们提供 Cloudflare Turnstile 求解器、身份覆盖项（UA、语言区域、时区、地理位置），以及贝塞尔曲线鼠标移动和基于高斯分布的打字间隔。
• 节省 Token 的 DOM。 两种查看页面的方式——上游 DOM 遍历器，相比原始 HTML 可减少 96% 的 Token；以及基于稳定 uid 的 CDP 无障碍树，即使重新渲染也能保持稳定。
• 全面对齐 DevTools。 可在 Chrome DevTools 中加载的性能跟踪、标准 .heapsnapshot 格式的堆快照，以及通过复用同一浏览器的 Lighthouse CLI 执行的 Lighthouse 审计。
• 会话往返传递。 将所有 Cookie（包括仅 HTTP Cookie）导出为 JSON，并在下次会话中重新导入。登录一次，随处复用。
• 模拟。 iPhone 15 Pro、Pixel 8、iPad Pro 和桌面设备预设；CPU 限速；Slow 3G / Fast 3G / 4G / 离线网络配置；强制设置 prefers-color-scheme。
• 屏幕录制。 以可配置的 FPS 将画面帧写入磁盘，格式为 JPEG 或 PNG。

工具目录

模块	工具
browser	启动、停止、状态
navigation	导航、后退、前进、重新加载、页面信息
tabs	新建 / 列出 / 切换 / 关闭
elements	点击、输入、清除、聚焦、选择、上传
query	查找元素、文本、属性、按钮、输入框
content	HTML、文本、交互树、滚动
storage	Cookie（document.cookie）、localStorage
logging	网络 + 控制台日志、等待请求
forms	填写表单、提交、按键、鼠标点击
utils	截图、执行 JS、等待、安全审计
stealth	绕过 Cloudflare、覆盖 UA / 语言区域 / 时区 / 地理位置
humanlike	human_click、human_type、estimated_typing_duration
emulation	视口、设备预设、CPU + 网络限速、媒体
devtools	开始 / 停止跟踪、获取堆快照
lighthouse	运行审计、检查 CLI 是否可用
screencast	开始 / 停止（写入画面帧目录）
accessibility	带稳定 uid 的 AX 快照、click_by_uid、describe_uid
cookies	导出 / 导入 / 列出 / 清除（CDP 级别，所有来源）
network_control	拦截 URL、额外请求头、绕过 Service Worker
permissions	授予 / 重置、列出名称
proxy	配置 / 清除（使用代理参数重启浏览器）
interception	mock_response、fail_requests、list、stop
screencast	+ export_screencast_mp4、check_ffmpeg_available

完整签名见 src/tools/*.py 中的文档字符串，并会在 MCP 握手时自动列出。

安装

已发布到 PyPI：https://pypi.org/project/zendriver-mcp/.

需要 Python 3.10+ 和 Chrome / Chromium 安装程序。

# Zero-setup, re-resolves on every run - great for Claude Desktop configs
uvx zendriver-mcp

# Or install once, invoke many
uv tool install zendriver-mcp
pipx install zendriver-mcp
pip install zendriver-mcp

与 Claude Desktop / Claude Code 搭配使用

{
  "mcpServers": {
    "zendriver": {
      "command": "uvx",
      "args": ["zendriver-mcp"]
    }
  }
}

无需克隆、无需 --directory、无需绝对路径。如果你更喜欢永久安装，也可以先运行 uv tool install zendriver-mcp，然后将 "command": "uvx" 替换为 "command": "zendriver-mcp"。

开发版检出

正在开发 zendriver-mcp 本身？克隆仓库并运行 uv sync，然后将 MCP 客户端指向该检出目录：

{
  "mcpServers": {
    "zendriver": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/zendriver-mcp", "run", "zendriver-mcp"]
    }
  }
}

CLI 的可选标志：

• --browser-path /path/to/chrome - 指定特定的 Chrome 二进制文件
• --transport stdio - 目前仅支持 stdio；等上游 mcp 发布稳定支持后，将加入 SSE/HTTP

30 秒快速浏览

# Ask the browser to start, log in once, save the session.
await start_browser()
await navigate("https://example.com/login")
await fill_form({"#email": "[email protected]", "#pw": "..."})
await export_cookies("~/sessions/example.json")

# Next run: skip the login entirely.
await start_browser()
await import_cookies("~/sessions/example.json")
await navigate("https://example.com/dashboard")

# Get an accessibility snapshot, click by stable uid.
snap = await get_accessibility_snapshot()
await click_by_uid("ax_1b2c3d4e")

# Record a performance trace while you click around.
await start_trace()
await human_click(selector="#buy-now")
await stop_trace("/tmp/buy-flow.json")   # loads in Chrome DevTools

# Run Lighthouse against the current browser.
await run_lighthouse("https://example.com", form_factor="mobile")

Token 优化的 DOM 遍历器

交互树会输出精简行，例如 {"id": 1, "t": "btn", "l": "Search", "r": "hdr"}：

• 精简键：t（类型）、l（标签）、r（区域）
• 智能标签：从 aria-label、aria-labelledby、关联的 <label>、placeholder、文本、title、alt 推断
• 噪声过滤：跳过 SVG 内部元素和嵌套的交互式子元素
• 区域标记：hdr、nav、main、side、ftr、dlg
• 类型压缩：button -> btn、checkbox -> chk 等

在 perplexity.ai 上报告的缩减效果：相比原始 HTML，Token 数量减少约 96%（约 11k -> 约 400）。

对于跨越多个操作的流程，优先使用 get_accessibility_snapshot + click_by_uid ——只要底层后端节点仍然存在，uid 就会保持有效，即使发生重新渲染也一样。

开发

uv sync
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest

CI 会在每次推送和 PR 上运行同样的四项检查。

路线图

原路线图中的所有内容都已在 0.2 / 0.3 版本中交付：

• 隐身：Cloudflare 求解器、UA / 语言区域 / 时区 / 地理位置
• 类人输入：贝塞尔鼠标路径、高斯按键计时
• DevTools 功能对等：跟踪记录、堆快照、Lighthouse
• 通过 ffmpeg 录制屏幕并导出 mp4
• 带稳定 uid 的无障碍树
• Cookie 导入/导出、拦截、额外请求头、权限
• 请求拦截 + 响应模拟（Fetch.enable）
• 代理配置（使用 --proxy-server 重启）
• 在富输出工具中采用 ToolResponse 封装
• PyPI 发布工作流（可信发布）

文档站点：https://bituq.github.io/zendriver-mcp/

接下来的工作将由实际使用情况决定。计划中的想法：

• 通过 Fetch 拦截进行逐请求代理路由
• 在 mock_response 中支持二进制正文
• 带模式的 Fetch.enable（比我们“全部匹配后再过滤”更快）

许可证

MIT。参见 LICENSE。

致谢

• Zendriver 承担了底层的大部分工作。
• Token 优化的 DOM 遍历器和最初的 49 工具基础来自 ShubhamChoulkar/Zendriver-MCP。 本项目最初是一个分支，之后逐渐形成了自己的特色和功能集。