# browser-mcp

将浏览器自动化框架封装为标准 MCP Server，使 AI 编程工具（Cursor、Windsurf、Cline/Roo Code）能通过 MCP 协议调用浏览器能力。

分享文档：

- 中文版：[docs/usage-guide.md](/Users/lizhongxuan/Desktop/skills/docs/usage-guide.md)
- English: [docs/usage-guide-en.md](/Users/lizhongxuan/Desktop/skills/docs/usage-guide-en.md)

## 功能概览

提供四个 MCP Tool：

| 工具 | 功能 |
|------|------|
| `browser_action` | 在持久页面上执行简化自然语言操作，支持多轮互动 |
| `map_and_extract_ui` | 提取网页结构化 UI 信息（清洗后的 DOM + 无障碍树） |
| `intercept_network_api` | 嗅探页面网络 API 请求与响应 |
| `visual_inspect` | 获取页面全页截图（Base64 编码） |

核心特性：
- 默认优先使用浏览器 CDP 可见模式（自动探测 `9222`）
- 支持 stdio 和 SSE 双传输模式
- Docker 容器化一键部署
- 会话持久化（跨调用保持登录状态）
- playwright-stealth 反检测集成
- 上下文压缩（控制返回数据量，避免超出 AI 上下文窗口）

## 快速开始

### 方式一：Docker 部署（推荐）

```bash
# 克隆项目
git clone <repo-url>
cd browser-use-mcp-server

# 启动服务（SSE 模式，监听 8000 端口）
docker-compose up -d

# 查看日志
docker-compose logs -f
```

容器启动后会自动检测 Chromium 浏览器是否可用，检测通过后以 SSE 模式启动 MCP Server。
如果本机 Chrome 已用 `--remote-debugging-port=9222` 启动，服务会默认接管该可见浏览器。

### 方式二：本地开发

```bash
# 安装依赖
pip install -e '.[dev]'

# 安装 Playwright 浏览器
playwright install chromium

# 以 stdio 模式启动（默认）
python -m src

# 或以 SSE 模式启动
MCP_TRANSPORT=sse python -m src
```

## 传输模式

### stdio 模式

适用于本地 IDE 直接集成。IDE 以子进程方式启动 MCP Server，通过标准输入输出通信。

```bash
python -m src
# 默认 MCP_TRANSPORT=stdio
```

### SSE 模式

适用于 Docker 部署或远程访问。MCP Server 启动 HTTP 服务，通过 Server-Sent Events 通信。

```bash
MCP_TRANSPORT=sse MCP_PORT=8000 python -m src
# SSE 端点: http://localhost:8000/sse
```

默认会优先自动探测 `127.0.0.1:9222` 和 `host.docker.internal:9222` 的 CDP 端口。
如果需要手动指定，可设置 `MCP_CDP_ENDPOINT`。

## IDE 配置

### Cursor

将以下内容添加到 Cursor 的 MCP 配置中（参考 `configs/cursor_mcp.json`）：

**stdio 模式（本地运行）：**
```json
{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**SSE 模式（连接 Docker 容器）：**
```json
{
  "mcpServers": {
    "browser-use-mcp-server-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

### Windsurf

参考 `configs/windsurf_mcp_config.json`：

**stdio 模式：**
```json
{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**SSE 模式：**
```json
{
  "mcpServers": {
    "browser-use-mcp-server-sse": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}
```

### Cline / Roo Code

参考 `configs/cline_mcp.json`：

**stdio 模式：**
```json
{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**SSE 模式：**
```json
{
  "mcpServers": {
    "browser-use-mcp-server-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```

## 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `MCP_TRANSPORT` | 传输模式：`stdio` 或 `sse` | 本地: `stdio`，Docker: `sse` |
| `MCP_HOST` | 监听地址（SSE 模式） | `0.0.0.0` |
| `MCP_PORT` | 监听端口（SSE 模式） | `8000` |
| `MCP_LOG_LEVEL` | 日志级别 | `INFO` |
| `MCP_STORAGE_PATH` | 会话存储路径 | 本地: `./storage`，Docker: `/data/storage` |
| `MCP_DEFAULT_TIMEOUT` | 默认超时时间（秒） | `120` |
| `MCP_DEFAULT_MAX_TOKENS` | 默认最大 Token 数 | `8000` |
| `MCP_CDP_ENDPOINT` | CDP 地址，默认 `auto` 自动探测 | `auto` |

## 简化交互

新增 `browser_action` tool，适合 MCP 多轮互动。默认 `session_id="default"`，会持续复用同一个页面。

示例：

```json
{"instruction":"打开网址 baidu.com"}
```

```json
{"instruction":"搜索A股行情，打开第二个网址"}
```

返回示例：

```json
{
  "success": true,
  "message": "Browser action executed successfully",
  "session_id": "default",
  "actions": ["searched A股行情", "opened result 2"],
  "page_title": "...",
  "current_url": "..."
}
```

## 工具详细说明

### map_and_extract_ui

提取网页结构化 UI 信息，包括清洗后的 DOM 和无障碍树。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 目标 URL |
| `instructions` | string | 否 | 页面交互指令（如点击、滚动等） |
| `target_selector` | string | 否 | CSS 选择器，限定提取范围 |
| `include_styles` | bool | 否 | 是否启用 CSS 还原（默认 false） |
| `session_id` | string | 否 | 会话 ID，用于跨调用保持状态 |
| `timeout` | int | 否 | 超时秒数（默认 120） |
| `max_tokens` | int | 否 | 最大 Token 数（默认 8000） |

**返回格式：**
```json
{
  "cleaned_html": "<div>...</div>",
  "accessibility_tree": "...",
  "page_title": "页面标题",
  "current_url": "https://example.com",
  "estimated_tokens": 3500,
  "truncated": false
}
```

### intercept_network_api

嗅探页面网络 API 请求与响应，自动过滤静态资源，仅保留 XHR/Fetch 数据接口。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 目标 URL |
| `instructions` | string | 是 | 页面交互指令（触发 API 调用） |
| `session_id` | string | 否 | 会话 ID |
| `timeout` | int | 否 | 超时秒数（默认 120） |
| `max_tokens` | int | 否 | 最大 Token 数（默认 8000） |

**返回格式：**
```json
{
  "api_calls": [
    {
      "url": "https://api.example.com/data",
      "method": "GET",
      "request_payload": null,
      "response_body": {"key": "value"},
      "status_code": 200,
      "truncated": false
    }
  ],
  "estimated_tokens": 1200,
  "truncated": false
}
```

> 注：单个 API 响应体超过 50KB 时会被截断，`truncated` 标记为 `true`。

### visual_inspect

获取页面全页截图，以 Base64 编码返回，适用于多模态 AI 视觉核对。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 目标 URL |
| `instructions` | string | 否 | 页面交互指令 |
| `session_id` | string | 否 | 会话 ID |
| `timeout` | int | 否 | 超时秒数（默认 120） |

**返回格式：**
```json
{
  "screenshot_base64": "iVBORw0KGgo...",
  "page_title": "页面标题",
  "current_url": "https://example.com"
}
```

## 错误处理

所有工具在异常情况下返回统一的错误结构：

```json
{
  "error": true,
  "error_type": "timeout | navigation | blocked | internal",
  "error_message": "错误描述",
  "blocked": false,
  "screenshot_base64": null,
  "partial_result": null
}
```

- `navigation`：URL 无法访问、DNS 解析失败
- `timeout`：操作超时，`partial_result` 中包含已完成的部分数据
- `blocked`：被反爬拦截，`screenshot_base64` 中包含拦截页面截图
- `internal`：服务内部异常

## 开发

```bash
# 安装开发依赖
pip install -e '.[dev]'

# 运行测试
pytest

# 运行测试（含覆盖率）
pytest --cov=src

# 仅运行属性测试
pytest tests/test_*_properties.py
```

## 项目结构

```
browser-use-mcp-server/
├── src/
│   ├── __main__.py          # 启动入口
│   ├── server.py            # MCP Server，Tool 注册与传输配置
│   ├── config.py            # 配置管理（环境变量）
│   ├── models.py            # 核心数据结构
│   ├── tools/               # 三个 MCP Tool 实现
│   │   ├── map_and_extract_ui.py
│   │   ├── intercept_network_api.py
│   │   └── visual_inspect.py
│   └── services/            # 共享服务模块
│       ├── session_manager.py
│       ├── dom_cleaner.py
│       ├── context_compressor.py
│       └── stealth.py
├── configs/                 # IDE 配置示例
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── tests/
```

## 许可证

MIT