Octo MCP

🚀 Octo Browser MCP 服務器

Octo Browser MCP 服務器是為 Octo Browser （一款用於多賬戶操作的反檢測瀏覽器）打造的 MCP（模型上下文協議）服務器。該服務器能讓像 Claude 這樣的 AI 助手通過自然語言控制 Octo Browser 配置文件。

🚀 快速開始

要使用 Octo Browser MCP 服務器，你需要先完成安裝和配置，然後添加 MCP 服務器並重啟 Claude Code 以加載新工具。

✨ 主要特性

• 配置文件管理：啟動、停止和列出 Octo Browser 配置文件。
• 按名稱搜索：使用雲 API 按名稱查找配置文件（需要 API 令牌）。
• 一次性配置文件：創建使用後即刪除的臨時配置文件。
• 瀏覽器自動化：通過 CDP 實現基於 Playwright 的完整瀏覽器控制。
• 截圖捕獲：對頁面或元素進行截圖。
• 多標籤支持：管理多個瀏覽器標籤。
• Docker 兼容：可與在 Docker 或遠程主機上運行的 Octo Browser 配合使用。

📦 安裝指南

從 PyPI 安裝

pip install octo-mcp

從源代碼安裝

git clone https://github.com/anthropics/octo-mcp.git
cd octo-mcp
pip install -e .

安裝 Playwright

playwright install chromium

🛠️ 配置說明

環境變量

獲取 API 令牌

1. 打開 Octo Browser。
2. 轉到 設置 → API。
3. 複製你的 API 令牌。

僅在按名稱搜索配置文件時需要 API 令牌，基本的配置文件操作無需此令牌。

💻 使用示例

添加 MCP 服務器

# 基本設置（僅本地 API）
claude mcp add octo-mcp -- python -m octo_mcp.server

# 帶身份驗證（推薦）
claude mcp add octo-mcp \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -- python -m octo_mcp.server

# 帶雲 API 的完整設置（支持按配置文件名稱搜索）
claude mcp add octo-mcp \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -e OCTO_API_TOKEN="your_api_token" \
  -- python -m octo_mcp.server

重啟 Claude Code

添加 MCP 服務器後，重啟 Claude Code 以加載新工具。

🛠️ 可用工具

配置文件管理

配置文件搜索（需要 API 令牌）

瀏覽器連接

導航

交互

信息提取

JavaScript

標籤管理

💬 示例對話

用戶：啟動我的配置文件 "work_account" 並訪問 google.com

Claude：我將啟動配置文件並導航到 Google。

[使用 octo_start_profile_by_name，名稱為 "work_account"]
配置文件 'work_account' 已啟動。
WebSocket 端點：ws://localhost:52341/devtools/browser/abc123

[使用 browser_connect 連接到 WebSocket 端點]
已連接到瀏覽器。

[使用 browser_navigate 訪問 url="https://google.com"]
已導航到 https://google.com

[使用 browser_screenshot]
[顯示 Google 主頁的截圖]

配置文件正在運行並顯示 Google 主頁。

🐳 Docker / 遠程設置

如果 Octo Browser 在不同的主機（如 Docker 中）上運行，請設置 OCTO_HOST 變量：

claude mcp add octo-mcp \
  -e OCTO_HOST="192.168.1.100" \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -- python -m octo_mcp.server

服務器會自動將 WebSocket URL 從 127.0.0.1 重寫為配置的主機。

🐞 故障排除

"Octo Browser API 不可用"

確保 Octo Browser 正在運行。打開應用程序時，本地 API 會自動啟動。

"OCTO_API_TOKEN 未設置"

在未使用 API 令牌的情況下使用 octo_find_profile_by_name 或 octo_search_profiles 時會出現此錯誤。你可以：

1. 將 API 令牌添加到 MCP 配置中。
2. 使用 octo_start_profile 和 UUID 代替（從 Octo Browser UI 獲取 UUID）。

"配置文件未找到"

配置文件名稱必須完全匹配（區分大小寫）。使用 octo_search_profiles 查找可用的配置文件。

WebSocket 連接失敗

如果 Octo Browser 在不同的主機上運行：

1. 確保端口 58888 可訪問。
2. 確保 CDP 端口（每個配置文件隨機）可訪問。
3. 將 OCTO_HOST 設置為正確的 IP 地址。

🛠️ 開發指南

環境搭建

git clone https://github.com/anthropics/octo-mcp.git
cd octo-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

運行測試

pytest

代碼風格檢查

ruff check .
ruff format .

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 文件瞭解詳細信息。

🔗 相關鏈接

• Octo Browser
• Octo Browser API 文檔
• 模型上下文協議
• Claude Code