Skip to main content
Glama
lizhongxuan

browser-mcp

by lizhongxuan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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 上下文窗口）

Related MCP server: Browser Automation MCP

快速开始

方式一：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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers