Browser MCP

Derived from internal Hermes project.

Agent-native browser control MCP server — 让任何支持 MCP 的 AI agent 都能浏览网页。

为什么需要这个？

现有的浏览器 MCP（Playwright、Puppeteer）是给程序员写代码用的底层 API。这个 MCP 是给 LLM agent 用的：

• Accessibility tree snapshot — agent "看到"的是可读的 DOM 树，不是原始 HTML
• Ref ID 交互 — click("@e5") 就行，不用写 CSS 选择器
• 本地运行 — 不需要云端浏览器，不需要 API key
• 开箱即用 — 13 个工具覆盖浏览器操作 + 网络调试 + 测试用例录制

工作原理

MCP 客户端 (Claude Code / Cursor / ZCode ...)
        │  stdio
        ▼
browser-mcp (本仓库，Python MCP server)
        │  subprocess
        ▼
agent-browser CLI  ──►  本地 Chrome (headless 或 headed)

browser-mcp 是一层薄封装，把 agent-browser CLI 的能力以 MCP 工具的形式暴露给 LLM agent。agent 通过 ref ID 与页面交互，不用写选择器。

安装

前置依赖

需要 Python ≥ 3.10 和 Node.js（用于安装 agent-browser）。

第 1 步：安装 agent-browser 并下载 Chrome

# 安装 CLI（需要 Node.js）
npm install -g agent-browser

# 下载它自带的 Chrome for Testing（首次安装必做）
agent-browser install

验证：

agent-browser --version
agent-browser open example.com && agent-browser snapshot -i
# 能看到页面的可交互元素列表，说明 agent-browser 就绪

第 2 步：安装 browser-mcp

git clone https://github.com/huaka1/browser-mcp.git
cd browser-mcp

# 建议用虚拟环境
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 可编辑安装（同时注册 `browser-mcp` 命令行入口）
pip install -e .

验证：

browser-mcp --help               # 或：python -m browser_mcp.server

一键安装（让 Agent 帮你装）

不想手动跑命令？把下面这段 prompt 复制给你的 AI agent（Claude Code / Cursor / ZCode 等），它会自己执行安装、生成配置、并引导你验证。

请帮我安装并配置 browser-mcp（一个让 AI agent 控制浏览器的 MCP server）。
按步骤执行，每步验证通过后再进入下一步；失败就停下来告诉我原因和修复建议。

【前提检查】
- 跑 `node --version`；失败就提示我装 Node.js（macOS: `brew install node`）
- 跑 `python3 --version` 确认 ≥ 3.10；失败就提示我装 Python 3.10+

【1. 安装浏览器引擎】
  npm install -g agent-browser
  agent-browser install              # 下载 Chrome for Testing，约 1-2 分钟
  验证：agent-browser open example.com && agent-browser snapshot -i
        能列出页面可交互元素即成功

【2. 克隆并安装 browser-mcp】
  git clone https://github.com/huaka1/browser-mcp.git ~/browser-mcp
  cd ~/browser-mcp
  python3 -m venv .venv
  source .venv/bin/activate          # Windows: .venv\Scripts\activate
  pip install -e .
  验证：`python -m browser_mcp.server` 能启动（或 browser-mcp 在 PATH 中）

【3. 生成 MCP 配置 — 关键：合并而非覆盖】
  - 用 `~/browser-mcp/.venv/bin/python` 的绝对路径作为 command
  - 定位我的 MCP 配置文件：优先当前项目 ./.mcp.json，其次 ~/.claude.json
  - 若文件已存在：解析 JSON，在 mcpServers 下新增 "browser" 键（保留其它配置）
  - 若不存在：新建文件，写入 {"mcpServers": { ... }}
  - browser 配置内容：
      "browser": {
        "command": "<venv python 绝对路径>",
        "args": ["-m", "browser_mcp.server"],
        "env": { "BROWSER_MCP_HEADED": "1" }
      }

【4. 收尾】
  告诉我重启 MCP 客户端以加载新配置。
  重启后引导我调用 browser_navigate 打开 https://example.com 做最终验证——
  返回页面快照即代表安装链路打通。

提示：prompt 里默认开启有头模式（BROWSER_MCP_HEADED=1），方便你看到浏览器在干什么。如果旧 daemon 还在 headless 跑导致看不到窗口，让 agent 执行 agent-browser close --all 后重试即可。

配置 MCP 客户端

在你的 MCP 客户端配置里添加一个 browser server。最简单的方式是直接用 Python 模块启动：

{
  "mcpServers": {
    "browser": {
      "command": "/你/克隆的路径/browser-mcp/.venv/bin/python",
      "args": ["-m", "browser_mcp.server"],
      "env": {
        "BROWSER_MCP_HEADED": "1"
      }
    }
  }
}

仓库里有一份现成模板 .mcp.json.example，复制成 .mcp.json 后改路径即可。

command 一定要指向你本机的 venv python 绝对路径，否则 MCP 客户端找不到 browser_mcp 包。如果用的是全局 pip install，可以直接写 "command": "browser-mcp"、去掉 args。

各客户端配置文件位置

客户端	配置文件
Claude Code	~/.claude.json（全局）或项目 .mcp.json
Cursor / Windsurf	各自的 MCP 设置面板
ZCode	项目 .mcp.json

配置完成后重启客户端，确认 browser_* 工具已加载。

想看到浏览器窗口（有头模式）

默认 headless，看不到浏览器在干什么。设环境变量即可显示窗口：

"env": {
  "BROWSER_MCP_HEADED": "1"
}

⚠️ agent-browser 是 daemon 模式，--headed 只在 daemon 首次启动时生效。如果之前已经有 headless daemon 在跑，新设的有头模式会被忽略。遇到这种情况，在终端跑 agent-browser close --all 关掉旧 daemon，再重新触发 MCP 工具调用即可。

首次验证

配置好后，让 agent 执行一个最简单的流程来确认链路通了：

• 调用 browser_navigate 打开 https://example.com
• 调用 browser_snapshot —— 应返回页面的可交互元素列表（链接、按钮 + ref ID）
• 调用 browser_vision —— 应返回页面截图

三条都成功，说明安装完成。

工具列表

浏览器操作

工具	说明
browser_navigate	导航到 URL，返回页面快照
browser_snapshot	获取页面 accessibility tree + ref ID
browser_click	点击元素（通过 ref ID）
browser_type	在输入框中输入文本
browser_press	按键盘按键
browser_scroll	滚动页面
browser_back	浏览器后退
browser_vision	截图
browser_console	获取控制台输出 / 执行 JS
browser_get_images	列出页面图片

网络层调试

工具	说明
browser_get_network_logs	获取网络请求日志（支持 URL/方法/状态码/类型过滤）
browser_get_response_body	查看请求的完整详情（headers + response body）
browser_intercept_request	拦截/模拟/阻断请求（block ads, mock API）

测试用例录制（无感留痕 + 导出）

工具	说明
browser_list_steps	列出当前 session 缓冲区里已留痕的操作步骤
browser_export_steps	把操作步骤导出成 jsonl 测试用例，同时保存登录态

录制出的 jsonl 可让 agent 自己读回、用 role+name 重新定位元素重放，做无代码 E2E 回归。导出目录由 BROWSER_MCP_E2E_DIR 指定。

环境变量

变量	说明	默认
BROWSER_MCP_HEADED	1 显示浏览器窗口（非 headless）	headless
BROWSER_MCP_DEBUG	1 启用调试日志	关
BROWSER_MCP_E2E_DIR	jsonl 测试用例导出目录	无

License

MIT