MCP Browser

Model Control Protocol（MCP）的无头浏览器接口。

功能

• 使用Playwright进行无头浏览器自动化
• 浏览器交互的Web UI
• 实时更新的WebSocket通信
• 实时浏览器事件订阅系统
• 与MCP集成的AI代理

预备条件

• 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设置

# 克隆仓库
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 /：Web 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 Browser支持通过WebSocket进行实时事件订阅。这允许客户端接收浏览器事件，包括：

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

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

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

许可证

MIT