browser-mcp

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

分享文档：

• 中文版：docs/usage-guide.md
• English: 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 部署（推荐）

# 克隆项目
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 启动，服务会默认接管该可见浏览器。

方式二：本地开发

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

# 安装 Playwright 浏览器
playwright install chromium

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

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

传输模式

stdio 模式

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

python -m src
# 默认 MCP_TRANSPORT=stdio

SSE 模式

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

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 模式（本地运行）：

{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

SSE 模式（连接 Docker 容器）：

{
  "mcpServers": {
    "browser-use-mcp-server-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Windsurf

参考 configs/windsurf_mcp_config.json：

stdio 模式：

{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

SSE 模式：

{
  "mcpServers": {
    "browser-use-mcp-server-sse": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}

Cline / Roo Code

参考 configs/cline_mcp.json：

stdio 模式：

{
  "mcpServers": {
    "browser-use-mcp-server": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

SSE 模式：

{
  "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"，会持续复用同一个页面。

示例：

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

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

返回示例：

{
  "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）

返回格式：

{
  "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）

返回格式：

{
  "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）

返回格式：

{
  "screenshot_base64": "iVBORw0KGgo...",
  "page_title": "页面标题",
  "current_url": "https://example.com"
}

错误处理

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

{
  "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：服务内部异常

开发

# 安装开发依赖
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