<div align="center">

Octo Browser MCP Server

Control antidetect browser profiles with AI through the Model Context Protocol

Installation · Quick Start · Tools Reference · Examples · Architecture

</div>

Why This Exists

Managing hundreds of antidetect browser profiles manually is tedious. This MCP server bridges Octo Browser and AI assistants (Claude Code, Cursor, etc.), enabling natural language control over browser profiles and full browser automation through CDP.

Instead of clicking through UIs or writing scripts, just tell your AI:

"Start profile 5249_US, go to google.com, and take a screenshot"

The AI handles the rest -- finding the profile, launching it, connecting via CDP, navigating, and capturing the result.

Key Features

• Profile Lifecycle -- Start, stop, find, and manage Octo Browser profiles via Local and Cloud APIs
• Browser Automation -- Full Playwright-based control: navigate, click, type, scroll, screenshot
• Dual API Support -- Local API (port 58888) for profile control + Cloud API for search and management
• One-Time Profiles -- Temporary profiles that self-destruct after use (ideal for scraping)
• Multi-Tab Control -- Open, switch, and close browser tabs programmatically
• Remote/Docker Ready -- Automatic WebSocket URL rewriting for non-localhost setups
• Rate Limit Handling -- Built-in retry with exponential backoff for API throttling

Architecture

┌─────────────────────────────────────────────────────┐
│                   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)        │
                   └───────────────────────────────┘

Installation

From Source

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

From PyPI (coming soon)

pip install octo-mcp
playwright install chromium

Prerequisites

• Python 3.10+
• Octo Browser installed and running (download)
• Playwright Chromium (installed via playwright install chromium)

Quick Start

1. Add to Claude Code

# 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="[email protected]" \
  -e OCTO_PASSWORD="your_password" \
  -e OCTO_API_TOKEN="your_api_token" \
  -- octo-mcp

2. Or add to .claude/settings.json manually

{
  "mcpServers": {
    "octo-mcp": {
      "command": "octo-mcp",
      "env": {
        "OCTO_USERNAME": "[email protected]",
        "OCTO_PASSWORD": "your_password",
        "OCTO_API_TOKEN": "your_api_token"
      }
    }
  }
}

3. Restart Claude Code and verify

Ask Claude: "Check if Octo Browser is running" -- it will use octo_health_check.

Getting Your API Token

1. Open Octo Browser app
2. Go to Settings → API
3. Copy your API token

The API token is only needed for Cloud API operations (searching profiles by name, managing tags/proxies/extensions). Basic profile start/stop works without it.

Environment Variables

Tools Reference (34 tools)

Profile Management (Local API)

Profile Search & Management (Cloud API)

Team Resources (Cloud API)

Browser Connection

Navigation

Page Interaction

Information Extraction

JavaScript Execution

Tab Management

Usage Examples

Start a profile by name and automate

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).

Scrape with a temporary profile

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".

Manage profiles in bulk

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: ...)
  ...

Check fingerprint configuration

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

Remote / Docker Setup

When Octo Browser runs on a different machine, set OCTO_HOST:

claude mcp add octo-mcp \
  -e OCTO_HOST="192.168.1.100" \
  -e OCTO_USERNAME="[email protected]" \
  -e OCTO_PASSWORD="your_password" \
  -- octo-mcp

The server automatically rewrites WebSocket URLs from 127.0.0.1/localhost to your configured host, so CDP connections work seamlessly across networks.

Requirements for remote setup:

• Port 58888 (Local API) must be accessible
• CDP debug ports (random, per-profile) must be accessible
• Consider using SSH tunnel for security

Troubleshooting

Development

git clone https://github.com/mazamakasa/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

Tech Stack

• [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) -- Model Context Protocol server framework
• [Playwright](https://playwright.dev/python/) -- Browser automation via CDP (Chrome DevTools Protocol)
• [httpx](https://www.python-httpx.org/) -- Async HTTP client for Octo Browser APIs
• [Hatchling](https://hatch.pypa.io/) -- Modern Python build system

License

MIT License -- see LICENSE for details.

Author

Maksym Babenko -- GitHub · Telegram

Links

• Octo Browser -- Antidetect browser for multi-accounting
• Octo Browser API Docs
• Model Context Protocol -- Open protocol for AI-tool integration
• Claude Code