# browser-mcp-server

**Repository Path**: yanxi-mcp/browser-mcp-server

## Basic Information

- **Project Name**: browser-mcp-server
- **Description**: browser mcp server
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Browser MCP

基于 Python MCP SDK 2.x 和 Playwright 的本地网页自动化 MCP Server。提供 `open_url`、`navigate`、`click`、`fill_form`、`screenshot`、`download`、`extract_content` 和多标签操作。服务只使用 stdio，适合由本机 MCP 客户端作为子进程启动。

## 安装

要求 Python 3.12 或 3.13、已安装的 Microsoft Edge 或 Playwright Chromium。在 `Browser-mcp` 目录中执行：

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
# 使用系统 Edge 时：
$env:BROWSER_MCP_BROWSER_CHANNEL = "msedge"
# 若使用 Playwright 自带 Chromium，先执行以下命令，并不设置 BROWSER_MCP_BROWSER_CHANNEL：
.\.venv\Scripts\python.exe -m playwright install chromium
```

`.env.example` 列出配置项供参考。此服务读取进程环境变量，不自动加载 `.env` 文件。启动前必须设置精确的主机白名单，例如：

```powershell
$env:BROWSER_MCP_ALLOWED_HOSTS = "example.com,docs.example.com"
$env:BROWSER_MCP_BROWSER_CHANNEL = "msedge"
.\.venv\Scripts\python.exe -m browser_mcp.server
```

启动后进程会等待 MCP 客户端通过 stdin/stdout 通信，不会打印交互提示。也可以运行安装后的 `browser-mcp.exe`。

## MCP 客户端配置

以下是通用的本地 stdio 配置示例；把绝对路径改成实际位置：

```json
{
  "mcpServers": {
    "browser": {
      "command": "D:\\python_workplace\\Browser-mcp\\.venv\\Scripts\\browser-mcp.exe",
      "env": {
        "BROWSER_MCP_ALLOWED_HOSTS": "example.com,docs.example.com",
        "BROWSER_MCP_BROWSER_CHANNEL": "msedge"
      }
    }
  }
}
```

## 工具与任务生命周期

1. `open_url(url)` 创建独立浏览器 Context，返回 `task_id`、`tab_id` 和当前 URL。
2. `navigate` 在现有标签中打开地址；`new_tab` 在同一任务内新增标签；`list_tabs` 查看标签；`close_tab` 关闭标签。
3. `extract_content` 提取 CSS 选择器匹配元素的可见文本，默认 `body`，最多返回 20,000 字符，可在 1–100,000 范围调整。`screenshot` 返回当前可视区域的 PNG 图像。
4. `fill_form` 接受 `{ "CSS 选择器": "文本" }`，只填值，不主动提交。
5. `click`、`download` 要求 `user_confirmed=true`。`download` 点击指定元素后将文件保存到下载目录，并返回文件路径和字节数；超过 25 MiB 的下载不会保存到目标目录。下载总耗时超过配置超时时会关闭该标签，以终止请求。
6. 完成后调用 `close_task` 释放 Context，同时清除该任务的 Cookie、Session 和临时下载。服务器退出也会关闭全部任务。

任务间使用独立 Context，不共享 Cookie 或 Session。弹出的新窗口属于当前任务，自动进入 `list_tabs`；每个任务最多 10 个标签，超额弹窗会被关闭。同时最多 5 个任务，超过上限会报错。

## 配置与安全边界

| 环境变量 | 默认值 | 作用 |
|---|---|---|
| `BROWSER_MCP_ALLOWED_HOSTS` | 必填 | 逗号分隔的精确主机名；子域名需要单独列出，不接受通配符 |
| `BROWSER_MCP_BROWSER_CHANNEL` | 无 | 例如 Windows 的 `msedge`；不填则使用 Playwright Chromium |
| `BROWSER_MCP_TIMEOUT_MS` | `15000` | 导航、定位和下载等待超时，范围 1–120000 毫秒 |
| `BROWSER_MCP_MAX_TASKS` | `5` | 最大同时任务数，范围 1–50 |
| `BROWSER_MCP_MAX_TABS` | `10` | 每任务最大标签数，范围 1–50 |
| `BROWSER_MCP_DOWNLOAD_DIR` | `downloads` | 下载保存目录；相对路径以启动工作目录为基准 |

直接导航、重定向与页面子请求都经过主机白名单检查；非 HTTP(S) 地址和带 URL 凭据的地址会被拒绝。Service Worker 被禁用，WebSocket 连接被关闭，以免绕过 HTTP 请求策略。白名单仅限制主机名，不能代替网络层访问控制；只应列入可信站点。服务只提供本机 stdio，不提供远程认证或共享访问。

**敏感操作确认由 MCP 客户端负责。** 客户端必须向用户展示目标和可能后果，并在获得真实用户确认后才传 `user_confirmed=true`。该布尔值本身无法证明用户身份。页面脚本也可能在填表、导航或加载时自动执行副作用；对交易、删除等高风险站点应同时使用站点自身的权限和确认机制。网页内容属于不可信输入，Agent 不应将其当作系统指令。

25 MiB 仅限制保存到目标目录的文件大小；Playwright 会先写临时文件，因此该检查不能限制下载过程的临时磁盘占用。运行时应为浏览器临时目录配置独立磁盘配额，并限制可访问站点。总超时可以缩短暴露时间，但不能替代磁盘配额。

## 验证

```powershell
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\ruff.exe check browser_mcp tests
```

浏览器集成测试使用本机 HTTP 页面和系统 Edge；若环境没有 Edge，可先安装后运行测试。