zen-mcp

zen-mcp

首个适用于 Zen Browser 的 MCP 服务。通过 Claude Code、Cursor 或任何 MCP 客户端自动化操作 Zen。

无需 Selenium。无需 Playwright。无需浏览器驱动。只需 WebSocket。

设置（2 分钟）

1. 使用远程调试启动 Zen

/Applications/Zen.app/Contents/MacOS/zen --remote-debugging-port 9222

专业提示：将 alias zen='open /Applications/Zen.app --args --remote-debugging-port 9222' 添加到 shell 配置中。之后只需运行 zen。

2. 添加到 Claude Code

# Option A: npm (recommended)
npm install -g zen-mcp

# Option B: Clone
git clone https://github.com/sh6drack/zen-mcp.git && cd zen-mcp && npm install

添加到 ~/.claude/mcp_servers.json：

{
  "mcpServers": {
    "zen-browser": {
      "command": "zen-mcp"
    }
  }
}

如果你选择克隆而非通过 npm 安装，请使用 "command": "node", "args": ["/absolute/path/to/zen-mcp/server.mjs"]

添加到 ~/.claude/settings.json：

{
  "permissions": {
    "allow": ["mcp__zen-browser__*"]
  }
}

就是这样。 启动新的 Claude Code 会话，即可使用 zen_* 工具。

20 个工具

浏览

工具	功能
zen_navigate	前往某个 URL
zen_list_pages	列出所有打开的标签页
zen_select_page	切换到某个标签页
zen_new_tab	打开新标签页
zen_close_tab	关闭标签页

查看

工具	功能
zen_snapshot	获取包含选择器的页面结构（筛选：all/interactive/form）
zen_screenshot	截取屏幕截图
zen_get_page_text	获取页面标题、URL 和文本
zen_get_form_fields	列出所有表单字段及其标签和值

交互

工具	功能
zen_click	点击元素
zen_fill	在输入框或文本区域中输入
zen_select_option	选择下拉选项
zen_check	切换复选框或单选框
zen_press_key	键盘输入（Enter、Tab、Ctrl+A 等）
zen_fill_form	一次填写多个字段
zen_scroll	滚动页面或滚动到某个元素

实用工具

工具	功能
zen_evaluate	在页面中运行 JavaScript
zen_wait	等待 N 毫秒
zen_wait_for	等待文本或元素出现
zen_reconnect	强制重新连接到 Zen

工作原理

Claude Code  ──stdio/MCP──>  zen-mcp  ──WebSocket/BiDi──>  Zen Browser

zen-mcp 通过 WebSocket 直接使用 WebDriver BiDi（W3C 标准）。填写表单时会使用原生值设置器并派发 input/change 事件，因此 React、Vue 和 Angular 应用都能正常运行。

运行良好的功能

• 导航、点击、填写表单 — 非常稳定，可处理 React/Vue/Angular
• 截图和读取页面 — 能可靠地提取内容
• 标签页管理 — 打开、关闭和切换标签页
• JavaScript 求值 — 在页面上下文中运行任意代码
• 键盘输入 — 快捷键、Enter、Tab 和组合键

已知限制

• Zen 继承了 Firefox 的 WebDriver BiDi 实现，该实现仍在完善中。Chrome 支持的一些高级 BiDi 命令目前可能尚不可用。
• 只能通过重启 Zen 清除僵尸会话（BiDi 的 session.end 按连接范围生效）。zen-mcp 会检测到这一情况，并告知你如何处理。
• 不支持文件上传或拖放（BiDi 规范限制）。

内置可靠性保障

• WebSocket 断开时，使用指数退避自动重新连接
• 上一个客户端崩溃时，恢复僵尸会话
• 连接重试（最多 3 次，并采用退避策略）
• 收到 SIGINT/SIGTERM 时正常关闭，防止会话遗留

故障排除

问题	解决方法
"Cannot connect to Zen Browser"	使用 --remote-debugging-port 9222 启动 Zen
"Maximum number of active sessions"	重启 Zen：killall zen && zen
连接持续断开	使用 zen_reconnect 强制建立新连接

配置

环境变量	默认值	说明
ZEN_DEBUG_PORT	9222	Zen 的远程调试端口

要求

• Zen Browser
• Node.js 20+

测试

node test-e2e.mjs   # 21 tests, needs Zen running

许可证

MIT