# browser-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io)
[![Playwright](https://img.shields.io/badge/powered%20by-Playwright-2EAD33)](https://playwright.dev)

一个为 **AI 而设计**的浏览器操作 MCP 服务器：22 个工具，让 AI 像人一样浏览、点击、输入、截图网页——不需要手写选择器。针对**办公自动化**场景做了专项优化：批量填表、数据提取、文件下载、PDF 存档、页面监控。

## 为什么是它

市面上大多数浏览器 MCP 要求 AI 写 CSS 选择器，这是 AI 操作网页失败的头号原因。browser-mcp 采用 **ref 编号体系**：

```
AI: browser_snapshot
←  [e1] <a> More information -> /about
   [e2] <input type=search> (搜索)
   [e3] <button> 登录

AI: browser_click { "ref": "e3" }     ← 点击"登录"，指哪打哪
✓  已点击：e3
```

snapshot 一次，拿到全部可交互元素的编号，之后所有操作只用 ref。元素找不到时，错误信息还会**附带当前页面状态摘录**，AI 能自行纠错重试，而不是瞎猜。

## 特性

- **ref 编号体系** — 快照给可交互元素编号，点击/输入/选择全部支持 ref 定位，AI 无需写选择器
- **智能等待** — 导航、点击后自动等待网络空闲（最多 4s），大幅减少手动 wait
- **登录态持久化** — cookie/localStorage 保存到磁盘（`storageState`），重启免重新登录
- **错误自解释** — 操作失败时返回当前 URL + 页面文本摘录 + 修复建议
- **办公自动化专项** — 批量填表、表格/列表数据提取（JSON/CSV）、文件下载落盘、页面 PDF 存档、后台变化监控
- **多浏览器回退** — Chromium → Edge → Chrome 依次尝试，Windows 无需下载浏览器即可使用
- **零构建** — 纯 ESM 单文件，`node index.mjs` 直接跑

## 演示

AI 通过 MCP 协议真实打开 example.com、识别元素、点击链接跳转：

![demo](docs/demo.png)

## 快速开始

```bash
git clone https://github.com/jixingyu999/browser-mcp.git
cd browser-mcp
npm install
npm test        # 端到端测试：真实打开网页、ref 点击、截图
```

### 接入 MCP 宿主（Claude Desktop / Cursor / WorkBuddy 等）

在宿主的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["/path/to/browser-mcp/index.mjs"],
      "env": {
        "BROWSER_MCP_HEADLESS": "0",
        "BROWSER_MCP_STORAGE_STATE": "/path/to/browser-mcp/storage.json"
      }
    }
  }
}
```

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `BROWSER_MCP_HEADLESS` | `1` | 设为 `0` 显示浏览器窗口，便于观察 AI 操作 |
| `BROWSER_MCP_OUTPUT_DIR` | 系统临时目录 | 截图输出目录 |
| `BROWSER_MCP_STORAGE_STATE` | （空） | 登录态文件路径，配置后自动加载/保存 |
| `BROWSER_MCP_TIMEOUT` | `10000` | 默认操作超时（毫秒） |

## 工具列表（22 个）

| 工具 | 说明 |
|------|------|
| `browser_navigate` | 打开 URL，自动补全协议前缀，完成后等待网络空闲 |
| `browser_snapshot` | 获取页面结构 + 可交互元素 ref 编号列表（核心工具） |
| `browser_click` | 点击元素：`ref` 优先，兼容 CSS / `text=` / `role=` |
| `browser_type` | 输入文字：ref 定位，可选清空、回车提交 |
| `browser_press_key` | 发送按键（Enter / Escape / Control+A …） |
| `browser_screenshot` | 截图，返回图片数据并保存文件 |
| `browser_get_text` | 获取页面或指定元素的文本 |
| `browser_evaluate` | 在页面上下文执行 JavaScript |
| `browser_scroll` | 上/下滚动 |
| `browser_select_option` | 选择下拉框选项 |
| `browser_wait` | 等待毫秒 / 元素出现 / 文本出现 |
| `browser_back` | 后退 |
| `browser_list_tabs` | 列出所有标签页 |
| `browser_tab` | 新建 / 切换标签页 |
| `browser_save_state` | 手动保存登录态 |
| `browser_fill_form` | **专项**：一次填完整个表单（文本/勾选/下拉混合，可自动提交） |
| `browser_extract_table` | **专项**：提取 `<table>` 为 JSON/CSV，可保存文件 |
| `browser_extract` | **专项**：按容器+字段映射抓取列表数据（JSON/CSV） |
| `browser_download` | **专项**：点击触发下载并自动保存到输出目录 |
| `browser_pdf` | **专项**：页面保存为 PDF 存档（无头模式） |
| `browser_watch` | **专项**：后台轮询监控页面变化（selector/text/JS 三种模式） |
| `browser_close` | 关闭浏览器（自动保存登录态） |

## 办公自动化专项

针对日常工作中最繁琐的重复流程，提供一站式工具：

| 场景 | 工具组合 | 效果 |
|------|----------|------|
| 填写报名/审批/申请表单 | `browser_fill_form` | 一次调用填完文本、勾选、下拉全部字段，自动提交 |
| 扒取后台数据/报表 | `browser_extract_table` / `browser_extract` | 表格、列表一键转 JSON/CSV 并落盘，CSV 转义正确处理 |
| 导出对账单/发票 | `browser_download` | 点击导出按钮自动等待下载并保存 |
| 网页存档留证 | `browser_pdf` | 页面转 A4 PDF 存档 |
| 盯库存/价格/审批状态 | `browser_watch` | 后台轮询监控，随时 check 是否变化 |

**示例：把后台报表自动存档**

```
1. browser_navigate        后台地址（登录态已持久化，免登录）
2. browser_fill_form       { fields: [{ref:"e3", value:"2026-09"}, {ref:"e5", value:true}], submitRef: "e6" }
3. browser_extract_table   { format: "csv", save: true, filename: "9月报表.csv" }
4. browser_pdf             { filename: "9月报表存档.pdf" }
```

## 典型用法（AI 工作流）

```
1. browser_navigate  https://example.com
2. browser_snapshot                       → 拿到元素 ref 列表
3. browser_type      { ref: "e2", text: "关键词", submit: true }
4. browser_click     { ref: "e3" }        → 点击搜索按钮
5. browser_screenshot                     → 截图查看结果
6. browser_get_text  { selector: "body" } → 提取结果文本
```

## 架构

```
AI 宿主（Claude Desktop / Cursor / WorkBuddy）
    │  MCP 协议（stdio / JSON-RPC）
    ▼
browser-mcp（Node.js，@modelcontextprotocol/sdk）
    │  Playwright API
    ▼
Chromium / Edge / Chrome（自动回退）
```

## Roadmap

- [ ] 网络嗅探工具（拦截 XHR / WebSocket，直接读数据）
- [ ] 游戏操作套件（鼠标坐标移动、按住不放、状态轮询）
- [ ] 失败视觉回退（选择器失败自动截图，AI 视觉定位）
- [ ] 操作轨迹回放（Playwright trace 生成）

## License

[MIT](LICENSE) © [jixingyu999](https://github.com/jixingyu999)