MCP Browser

MCP Browser

用于模型控制协议（MCP）的无头浏览器接口。

功能

• 使用 Playwright 自动化无头浏览器
• 用于浏览器交互的 Web 界面
• 通过 WebSocket 实时通信
• 实时浏览器事件订阅系统
• 与 MCP 集成，支持 AI Agent

前置条件

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

安装

一键安装

只需一条命令，即可在 Mac 上安装 MCP Browser：

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 Browser 需要 XQuartz（X11）才能正常显示。安装程序将：

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

如果遇到问题，请参阅排查 XQuartz 问题部分。

本地开发

使用 uv 设置

# Clone the repository
git clone https://github.com/yourusername/mcp-browser.git
cd mcp-browser

# Install dependencies
uv venv .venv
source .venv/bin/activate
uv pip install -e .

# Install Playwright browsers
python -m playwright install

本地运行

不使用 Xvfb 进行简单测试：

./simple_test.sh

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

./test_local.sh

Docker 部署

使用 Docker Compose 构建并运行：

# Set your MCP secret
export MCP_SECRET=your_secret_key

# Build and run
docker-compose up --build

或者使用提供的脚本：

./run.sh

配置

可设置以下环境变量：

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

API 端点

• GET /：Web 界面
• 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 Browser 支持通过 WebSocket 实时订阅事件。客户端可以据此接收浏览器事件，包括：

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

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

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

许可证

MIT