octo MCP

Octo浏览器MCP服务器

通过模型上下文协议使用AI控制反检测浏览器配置文件

安装 · 快速开始 · 工具参考 · 示例 · 建筑

______________________________________________________________________

为什么存在

手动管理数百个反检测浏览器配置文件是乏味的。此MCP服务器桥接 Octo浏览器 和 AI助手 （Claude Code、Cursor等），通过CDP实现对浏览器配置文件的自然语言控制和完全的浏览器自动化。

与其点击UI或编写脚本，不如告诉你的AI：

*“启动配置文件5249_US，转到google.com并截图”*

AI处理其余的事情——查找配置文件、启动配置文件、通过CDP连接、导航和捕获结果。

主要特点

• 配置文件生命周期 --通过本地和云API启动、停止、查找和管理Octo Browser配置文件
• 浏览器自动化 --完全基于剧作家的控制：导航、单击、键入、滚动、截图
• 双重API支持 --用于配置文件控制的本地API（端口58888）+用于搜索和管理的云API
• 一次性配置文件 --使用后自毁的临时型材（非常适合刮擦）
• 多选项卡控件 --以编程方式打开、切换和关闭浏览器选项卡
• 远程/Docker就绪 --非本地主机设置的自动WebSocket URL重写
• 费率限制处理 --API节流的带指数退避的内置重试

建筑

┌─────────────────────────────────────────────────────┐
│                   AI Assistant                       │
│              (Claude Code / Cursor)                  │
└──────────────────────┬──────────────────────────────┘
                       │ MCP Protocol (stdio)
┌──────────────────────▼──────────────────────────────┐
│              octo-mcp Server                         │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │   server.py  │ │ octo_client  │ │browser_manager│ │
│  │  34 MCP Tools│ │  Local+Cloud │ │  Playwright   │ │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘  │
└─────────┼────────────────┼────────────────┼──────────┘
          │                │                │
    ┌─────▼────┐   ┌──────▼──────┐  ┌──────▼──────┐
    │ MCP SDK  │   │  Octo APIs   │  │  CDP / WS   │
    │  stdio   │   │ :58888 Cloud │  │  Playwright │
    └──────────┘   └──────┬───────┘  └──────┬──────┘
                          │                 │
                   ┌──────▼─────────────────▼──────┐
                   │        Octo Browser           │
                   │   (antidetect Chromium)        │
                   └───────────────────────────────┘

安装

来源

git clone https://github.com/mazamaka/octo-mcp.git
cd octo-mcp
pip install -e .
playwright install chromium

来自PyPI（即将推出）

pip install octo-mcp
playwright install chromium

先决条件

• Python 3.10+
• Octo浏览器 已安装并正在运行(下载)
• 剧作家Chromium （通过安装 playwright install chromium)

快速开始

1.添加到克劳德代码

# Minimal setup (Local API only -- start/stop profiles by UUID)
claude mcp add octo-mcp -- octo-mcp

# Full setup (+ Cloud API for searching profiles by name)
claude mcp add octo-mcp \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -e OCTO_API_TOKEN="your_api_token" \
  -- octo-mcp

2.或添加到 .claude/settings.json 手动地

{
  "mcpServers": {
    "octo-mcp": {
      "command": "octo-mcp",
      "env": {
        "OCTO_USERNAME": "your@email.com",
        "OCTO_PASSWORD": "your_password",
        "OCTO_API_TOKEN": "your_api_token"
      }
    }
  }
}

3.重新启动Claude Code并验证

问克劳德： *“检查Octo浏览器是否正在运行”* --它将使用 octo_health_check.

获取您的API代币

1. 打开Octo浏览器应用程序
2. 首选 设置 → API
3. 复制您的API令牌

API令牌仅用于云API操作（按名称搜索配置文件、管理标签/代理/扩展）。基本配置文件启动/停止在没有它的情况下工作。

环境变量

工具参考（34个工具）

配置文件管理（本地API）

配置文件搜索和管理（云API）

团队资源（云API）

浏览器连接

导航

页面交互

信息抽取

JavaScript执行

选项卡管理

使用示例

按名称启动配置文件并自动执行

You: Start profile "work_US" and check my IP on whatismyipaddress.com

Claude: I'll start the profile, connect to it, and check your IP.

→ octo_start_profile_by_name(name="work_US")
  Profile 'work_US' (uuid: abc-123) started. ws_endpoint: ws://localhost:52341/...

→ browser_connect(ws_endpoint="ws://localhost:52341/...")
  Connected to browser.

→ browser_navigate(url="https://whatismyipaddress.com")
  Navigated to https://whatismyipaddress.com

→ browser_screenshot()
  [Screenshot showing IP address]

Your IP is 192.168.x.x (US location, matching profile proxy).

使用临时配置文件进行报废

You: Create a temp profile and scrape the title from news.ycombinator.com

Claude:
→ octo_start_one_time_profile(os="win")
  Temporary profile created. UUID: tmp-456. ws_endpoint: ws://...

→ browser_connect(ws_endpoint="ws://...")
→ browser_navigate(url="https://news.ycombinator.com")
→ browser_evaluate(script="document.title")
  Result: "Hacker News"

→ octo_stop_profile(uuid="tmp-456")
  Profile stopped and deleted.

The page title is "Hacker News".

批量管理配置文件

You: Find all profiles tagged "ads" and list them

Claude:
→ octo_search_profiles(tags=["ads"], limit=50)
  Found 12 profiles:
  - ads_US_01 (UUID: ...)
  - ads_UK_02 (UUID: ...)
  ...

检查指纹配置

You: Show me the fingerprint details for profile "5249_US"

Claude:
→ octo_find_profile_by_name(name="5249_US")
→ octo_get_profile(uuid="found-uuid")

  Profile: 5249_US
  Fingerprint:
    OS: win
    User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...
    Screen: 1920x1080
  Proxy: socks5://proxy.example.com:1080
  Extensions (2):
    - uBlock Origin v1.55
    - EditThisCookie v1.6

远程/Docker设置

当Octo Browser在另一台机器上运行时，设置 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" \
  -- octo-mcp

服务器自动重写WebSocket URL 127.0.0.1/localhost CDP连接可以无缝地跨网络工作。

远程设置要求：

• 端口58888（本地API）必须可访问
• CDP调试端口（随机，每个配置文件）必须可访问
• 考虑使用SSH隧道进行安全保护

故障排除

发展

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

# Lint & format
ruff check src/
ruff format src/

# Run tests
pytest

技术栈

• MCP-SDK --模型上下文协议服务器框架
• 剧作家 --通过CDP（Chrome DevTools协议）实现浏览器自动化
• httpx --Octo浏览器API的异步HTTP客户端
• 雏鸟 --现代Python构建系统

许可证

MIT许可证——见 许可证 了解详情。

作者

马克西姆·巴本科 -- · 电报

链接

• Octo浏览器 --多账户反检测浏览器
• Octo浏览器API文档
• 模型上下文协议 --AI工具集成的开放协议
• 克劳德代码