MCP 浏览器

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

特性

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

前提条件

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

安装

一行命令安装

要使用一个命令在 Mac 上安装 MCP 浏览器：

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 /: 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 浏览器支持通过 WebSockets 进行实时事件订阅。 这允许客户端在事件发生时接收浏览器事件，包括：

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

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

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

许可证

MIT