# 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

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

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

验证：

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

### 第 2 步：安装 browser-mcp

```bash
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 .
```

验证：

```bash
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 模块启动：

```json
{
  "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，看不到浏览器在干什么。设环境变量即可显示窗口：

```json
"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