MCP Browser

🚀 MCP 浏览器

MCP 浏览器是 Model Control Protocol (MCP) 的无头浏览器界面，它借助自动化技术与实时通信能力，为用户提供了便捷的浏览器交互体验，同时支持与 AI 代理的集成。

🚀 快速开始

MCP 浏览器是一个强大的工具，可用于自动化浏览器操作和与 MCP 集成。以下是快速开始使用该项目的步骤。

安装依赖

在开始之前，请确保你已经安装了以下依赖：

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

安装项目

你可以选择一键安装或手动安装项目：

一键安装

在 Mac 上，你可以使用以下命令进行一键安装：

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

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

手动安装

手动安装步骤如下：

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

注意事项

MCP 浏览器需要 XQuartz（X11）进行可视化。安装程序将自动检查是否已安装 XQuartz，如果未安装则自动安装，并尝试以多种方式启动 X11 服务器。如果自动方法失败，则会提示你手动启动。如遇问题，请参阅 解决 XQuartz 问题 部分。

✨ 主要特性

• 自动化操作：使用 Playwright 实现无头浏览器自动化，可高效执行各种浏览器任务。
• 网络交互：提供网络 UI 用于浏览器交互，方便用户进行操作。
• 实时更新：支持 WebSocket 通信以实现实时更新，确保信息的及时性。
• 事件订阅：具备实时浏览器事件订阅系统，可实时接收各类浏览器事件。
• AI 集成：集成 MCP 用于 AI 代理，拓展了应用场景。

📦 安装指南

一键安装

在 Mac 上，你可以使用以下命令进行一键安装：

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

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

手动安装

手动安装步骤如下：

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

XQuartz 要求

MCP 浏览器需要 XQuartz（X11）进行可视化。安装程序将自动处理 XQuartz 的安装和启动：

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

📚 详细文档

配置

可以设置以下环境变量：

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 许可证。