Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
将浏览器自动化框架封装为标准 MCP Server，使 AI 编程工具（Cursor、Windsurf、Cline/Roo Code）能通过 MCP 协议调用浏览器能力。
分享文档：
English: docs/usage-guide-en.md
提供四个 MCP Tool：
工具 | 功能 |
| 在持久页面上执行简化自然语言操作，支持多轮互动 |
| 提取网页结构化 UI 信息（清洗后的 DOM + 无障碍树） |
| 嗅探页面网络 API 请求与响应 |
| 获取页面全页截图（Base64 编码） |
核心特性：
默认优先使用浏览器 CDP 可见模式（自动探测 9222）
支持 stdio 和 SSE 双传输模式
Docker 容器化一键部署
会话持久化（跨调用保持登录状态）
playwright-stealth 反检测集成
上下文压缩（控制返回数据量，避免超出 AI 上下文窗口）
Related MCP server: Browser Automation MCP
# 克隆项目
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适用于本地 IDE 直接集成。IDE 以子进程方式启动 MCP Server，通过标准输入输出通信。
python -m src
# 默认 MCP_TRANSPORT=stdio适用于 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。
将以下内容添加到 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"
}
}
}参考 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"
}
}
}参考 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"
}
}
}变量名 | 说明 | 默认值 |
| 传输模式： | 本地: |
| 监听地址（SSE 模式） |
|
| 监听端口（SSE 模式） |
|
| 日志级别 |
|
| 会话存储路径 | 本地: |
| 默认超时时间（秒） |
|
| 默认最大 Token 数 |
|
| CDP 地址，默认 |
|
新增 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": "..."
}提取网页结构化 UI 信息，包括清洗后的 DOM 和无障碍树。
参数：
参数 | 类型 | 必填 | 说明 |
| string | 是 | 目标 URL |
| string | 否 | 页面交互指令（如点击、滚动等） |
| string | 否 | CSS 选择器，限定提取范围 |
| bool | 否 | 是否启用 CSS 还原（默认 false） |
| string | 否 | 会话 ID，用于跨调用保持状态 |
| int | 否 | 超时秒数（默认 120） |
| int | 否 | 最大 Token 数（默认 8000） |
返回格式：
{
"cleaned_html": "<div>...</div>",
"accessibility_tree": "...",
"page_title": "页面标题",
"current_url": "https://example.com",
"estimated_tokens": 3500,
"truncated": false
}嗅探页面网络 API 请求与响应，自动过滤静态资源，仅保留 XHR/Fetch 数据接口。
参数：
参数 | 类型 | 必填 | 说明 |
| string | 是 | 目标 URL |
| string | 是 | 页面交互指令（触发 API 调用） |
| string | 否 | 会话 ID |
| int | 否 | 超时秒数（默认 120） |
| 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。
获取页面全页截图，以 Base64 编码返回，适用于多模态 AI 视觉核对。
参数：
参数 | 类型 | 必填 | 说明 |
| string | 是 | 目标 URL |
| string | 否 | 页面交互指令 |
| string | 否 | 会话 ID |
| 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.pybrowser-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
Call a raw Chrome DevTools Protocol method. params are passed as kwargs.
Inputs: method (required), params.
Click at screen coordinates (x, y). button is 'left'/'right'/'middle'.
Inputs: x (required), y (required), button, clicks.
Close a tab. Without target, closes the active tab.
Inputs: target.
Return the active tab's targetId, url and title.
Inputs: no named parameters.
Switch to a real (non-internal) tab if the current one is chrome:// or stale.
Inputs: no named parameters.
Fill an input matched by selector with text.
Inputs: text (required), selector (required), clear_first.
Navigate the current tab to url. Returns the navigation result.
Inputs: url (required).
HTTP GET url (browser-less). Returns the response body. Optional
headers dict for authentication or custom request headers.
Inputs: url (required), headers, timeout.
Evaluate a JavaScript expression in the current tab (or an iframe target_id).
Inputs: expression (required), target_id.
List open page tabs.
Inputs: no named parameters.
Open a new browser tab. Returns the new tab's targetId.
Inputs: url.
Return current tab metadata: url, title, viewport and scroll sizes.
Inputs: no named parameters.
Press a key. modifiers is a bitfield: 1=Alt, 2=Ctrl, 4=Meta, 8=Shift.
Inputs: key (required), modifiers.
Capture a PNG screenshot. If path is omitted, a temp file is used.
Set max_dim to downscale results larger than that dimension.
Inputs: full, path, max_dim.
Scroll the wheel at (x, y) by dy vertical / dx horizontal pixels.
Inputs: x (required), y (required), dx, dy.
Start recording actions to a local directory.
Inputs: name, title.
Stop the active recording and return its directory.
Inputs: no named parameters.
Switch to tab by targetId or URL substring. Returns the sessionId.
Inputs: target (required).
Insert text into the focused element.
Inputs: text (required).
Set files on a file input matched by selector. path is the local file.
Inputs: path (required), selector (required).
Wait for seconds.
Inputs: seconds.
Wait for an element matching selector to appear. Set visible=True to
also require it to be rendered.
Inputs: selector (required), timeout, visible.
Wait until the current tab's readyState is 'complete'.
Inputs: timeout.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 23 tools
Most tools target distinct browser concerns—tabs, navigation, input, waiting, and screenshots—so an agent can usually pick the right one. The main overlaps are browser_type versus browser_fill for text entry and browser_current_tab versus browser_page_info for tab metadata, but their descriptions mostly clarify the intended use.
All tools share the browser_ prefix and use lowercase snake_case, creating a recognizable family pattern. However, not all names follow the verb_noun convention, with noun-phrase names like browser_page_info and browser_current_tab and bare abbreviations like browser_js and browser_cdp.
At 23 tools, the surface sits in the 16-25 range that feels heavy for an MCP server. Most tools earn their place, but a few niche or parallel helpers such as browser_ensure_real_tab, browser_http_get, and the recording pair could be considered auxiliary.
The toolset covers tab management, navigation, input actions, waiting, screenshots, uploads, JavaScript evaluation, and raw CDP access. Common browser operations like back, forward, reload, hover, and select are missing but can be worked around via browser_js or browser_cdp, so there are no blocking dead ends.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
