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