内容
# 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
