MCP 浏览器

Model Control Protocol (MCP) 的无头浏览器界面。

功能

• 使用 Playwright 实现无头浏览器自动化
• 提供网络 UI 用于浏览器交互
• 支持 WebSocket 通信以实现实时更新
• 实时浏览器事件订阅系统
• 集成 MCP 用于 AI 代理

先决条件

• Python 3.13+
• uv 用于依赖管理
• Docker（用于容器化部署）

安装

一键安装

要在 Mac 上使用一条命令进行安装：

curl -sSL https://raw.githubusercontent.com/neoforge-dev/mcp-browser/main/install_one_line.sh | bash

此命令将下载并运行安装程序，以避免常见问题。

手动安装

手动安装步骤如下：

1. 克隆该仓库
2. 运行安装脚本：

git clone https://github.com/neoforge-dev/mcp-browser.git
cd mcp-browser
./install.sh

XQuartz 要求

MCP 浏览器需要 XQuartz（X11）进行可视化。安装程序将：

1. 检查是否已安装 XQuartz，如果未安装则自动安装
2. 尝试以多种方式启动 X11 服务器
3. 如果自动方法失败，则提示手动启动

如遇问题，请参阅 解决 XQuartz 问题 部分。

本地开发

使用 uv 设置

# 克隆仓库
git clone https://github.com/yourusername/mcp-browser.git
cd mcp-browser

# 安装依赖项
uv venv .venv
source .venv/bin/activate
uv pip install -e .

# 安装 Playwright 浏览器
python -m playwright install

本地运行

无需 Xvfb 的简单测试：

./simple_test.sh

使用 Xvfb 进行完整测试（需要 X11）：

./test_local.sh

Docker 部署

使用 Docker Compose 构建并运行：

# 设置 MCP 密钥
export MCP_SECRET=your_secret_key

# 构建并运行
docker-compose up --build

或使用提供的脚本：

./run.sh

配置

可以设置以下环境变量：

• MCP_SECRET：用于 MCP 身份验证的密钥
• SERVER_PORT：服务器运行的端口（默认：7665）
• PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD：设为 1 可以跳过浏览器下载，仅在无头模式下运行

API 端点

• GET /：网络 UI
• GET /api/status：获取浏览器和 MCP 客户端状态
• WebSocket /ws：实时通信 WebSocket 端点
• WebSocket /ws/browser/events：用于订阅浏览器事件的 WebSocket 端点
• GET /api/browser/subscribe：订阅浏览器事件
• GET /api/browser/unsubscribe：取消订阅浏览器事件
• GET /api/browser/subscriptions：列出活动事件订阅

事件订阅

MCP 浏览器支持通过 WebSocket 实现实时事件订阅。这使得客户端能够实时接收浏览器事件，包括：

• 页面事件（导航、加载、错误）
• DOM 事件（突变、变化）
• 控制台事件（日志、警告、错误）
• 网络事件（请求、响应、错误）

有关 WebSocket 事件和事件订阅系统的详细文档，请参阅：

• WebSocket 事件文档
• 事件订阅示例

许可证

MIT