How do I use browser-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@browser-mcp open google.com and search for MCP" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

browser-mcp

by lizhongxuan

Overview Schema Related Servers Score Discussions

Python

Hybrid

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

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 installed

license - not found

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lizhongxuan/browser-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server