Skip to content

lizhongxuan/browser-mcp

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
.hypothesis
.hypothesis
 
 
.vscode
.vscode
 
 
configs
configs
 
 
docs
docs
 
 
src
src
 
 
tests
tests
 
 
Dockerfile
Dockerfile
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

browser-mcp

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

分享文档：

功能概览

提供四个 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

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages