金大哥 - octo-mcp MCP 详情

article

README

🚀 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

🛠️ 配置说明

环境变量

| 变量 | 描述 | 是否必需 | 默认值 | |------|------|----------|---------| | OCTO_HOST | Octo Browser 主机 | 否 | localhost | | OCTO_PORT | 本地 API 端口 | 否 | 58888 | | OCTO_USERNAME | Octo 账户邮箱（用于自动登录） | 否 | - | | OCTO_PASSWORD | Octo 账户密码 | 否 | - | | OCTO_API_TOKEN | 云 API 令牌（用于按名称搜索配置文件） | 否 | - |

获取 API 令牌

打开 Octo Browser。
转到设置 → API。
复制你的 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 以加载新工具。

🛠️ 可用工具

配置文件管理

| 工具 | 描述 | |------|------| | octo_health_check | 检查 Octo Browser 是否正在运行 | | octo_list_profiles | 列出活动（正在运行）的配置文件 | | octo_start_profile | 按 UUID 启动配置文件 | | octo_stop_profile | 停止正在运行的配置文件 | | octo_start_one_time_profile | 创建并启动临时配置文件 |

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

| 工具 | 描述 | |------|------| | octo_find_profile_by_name | 按精确名称查找配置文件 | | octo_start_profile_by_name | 按名称查找并启动配置文件 | | octo_search_profiles | 按名称或标签搜索配置文件 |

浏览器连接

| 工具 | 描述 | |------|------| | browser_connect | 通过 CDP 连接到正在运行的配置文件 | | browser_disconnect | 断开与浏览器的连接 |

交互

| 工具 | 描述 | |------|------| | browser_click | 点击元素或坐标 | | browser_type | 在元素中输入文本 | | browser_press_key | 按下键盘按键（如 Enter、Tab 等） | | browser_scroll | 滚动页面或元素 | | browser_hover | 悬停在元素上 | | browser_select | 在下拉菜单中选择选项 |

信息提取

| 工具 | 描述 | |------|------| | browser_screenshot | 截图（返回图像） | | browser_get_text | 获取元素的文本内容 | | browser_get_html | 获取页面或元素的 HTML | | browser_get_attribute | 获取元素的属性 | | browser_query_selector_all | 查找所有匹配的元素 | | browser_wait_for_selector | 等待元素出现 |

JavaScript

| 工具 | 描述 | |------|------| | browser_evaluate | 执行 JavaScript 并返回结果 |

标签管理

| 工具 | 描述 | |------|------| | browser_list_tabs | 列出打开的标签 | | browser_switch_tab | 按索引切换到标签 | | browser_new_tab | 打开新标签 | | browser_close_tab | 关闭当前标签 |

💬 示例对话

用户：启动我的配置文件 "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 时会出现此错误。你可以：

将 API 令牌添加到 MCP 配置中。
使用 octo_start_profile 和 UUID 代替（从 Octo Browser UI 获取 UUID）。

"配置文件未找到"

配置文件名称必须完全匹配（区分大小写）。使用 octo_search_profiles 查找可用的配置文件。

WebSocket 连接失败

如果 Octo Browser 在不同的主机上运行：

确保端口 58888 可访问。
确保 CDP 端口（每个配置文件随机）可访问。
将 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-mcp