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 許可證。