octobrowser-mcp

Hand your AI assistant the wheel of Octo Browser — antidetect profiles, driven in plain language.

Unofficial, community-built · not affiliated with or endorsed by Octo Browser. “Octo Browser” and its logo are trademarks of their respective owner.

What it does · How it fits together · 60-second start · Configuration · The tool belt · In practice · Troubleshooting

What it does

Driving fleets of antidetect profiles by hand is a grind. OctoBrowser-MCP puts an MCP relay between your AI assistant (Claude Code, Cursor, …) and Octo Browser, so a sentence does the work of a dozen clicks:

"Start profile 5249_US, open google.com, and grab a screenshot."

The assistant finds the profile, launches it through Octo's local API, latches onto the running browser over CDP, navigates, and hands back the picture — no scripts, no dashboards.

What you get:

• 🐙 Whole profile lifecycle — launch, halt, look up and manage profiles across Octo's local and cloud APIs.

• 🎛️ Real browser steering — navigate, click, type, scroll, screenshot, evaluate JS, all over Playwright/CDP.

• ⚡ Throwaway profiles — spin up one-time profiles that vanish on halt; perfect for scraping.

• 🗂️ Multi-tab command — open, switch and close tabs on demand.

• 🌐 Remote & Docker aware — WebSocket endpoints get rehomed to your configured host automatically.

• 🛡️ Polite under throttle — bounded retries that honour Retry-After on HTTP 429.

Related MCP server: Multilogin Browser MCP

How it fits together

60-second start

Install from source

git clone https://github.com/eforus-overseer/octobrowser-mcp.git
cd octobrowser-mcp
pip install -e .
playwright install chromium

Requires Python 3.10+, Octo Browser running (download), and the Playwright Chromium build.

Register with Claude Code

# Local API only — launch/halt profiles by UUID. No email, password or token needed.
claude mcp add octobrowser-mcp -- octobrowser-mcp

# Full setup — all three creds are OPTIONAL; add them only for cloud search by name, tags, proxies
claude mcp add octobrowser-mcp \
  -e OCTO_USERNAME="you@email.com" \    # optional — only for cloud auto sign-in
  -e OCTO_PASSWORD="your_password" \    # optional — only for cloud auto sign-in
  -e OCTO_API_TOKEN="your_api_token" \  # optional — only for cloud calls
  -- octobrowser-mcp

Prefer editing config by hand? Drop this into .claude/settings.json. The entire env block is optional — omit it for local-only use, or include only the fields you need:

{
  "mcpServers": {
    "octobrowser-mcp": {
      "command": "octobrowser-mcp",
      "env": {
        "OCTO_USERNAME": "you@email.com",   // optional — cloud auto sign-in only
        "OCTO_PASSWORD": "your_password",    // optional — cloud auto sign-in only
        "OCTO_API_TOKEN": "your_api_token"   // optional — cloud calls only
      }
    }
  }
}

The env keys above are shown for completeness — none are required. With no credentials at all, you still get the full local profile lifecycle and browser steering; the cloud-only tools simply stay dormant.

Restart the client and ask: "Check if Octo Browser is running" — it will reach for octo_health_check.

Where's the API token? Octo Browser app → Settings → API. It's only needed for cloud calls (search by name, tags, proxies, extensions), and those need an active subscription. Local launch/halt works without it.

Configuration

Everything is environment-driven:

Everything below is optional — the server runs with zero configuration against your local Octo Browser.

The tool belt (37 tools)

In practice

Launch by name and automate

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

→ octo_start_profile_by_name(name="work_US")   ws://localhost:52341/…
→ browser_connect(ws_endpoint="ws://localhost:52341/…")
→ browser_navigate(url="https://whatismyipaddress.com")
→ browser_screenshot()

Your IP resolves to a US location, matching the profile's proxy.

Scrape with a throwaway profile

You: Spin up a temp profile and read the title of news.ycombinator.com

→ octo_start_one_time_profile(os="win")         uuid: tmp-456, ws://…
→ browser_connect(ws_endpoint="ws://…")
→ browser_navigate(url="https://news.ycombinator.com")
→ browser_evaluate(script="document.title")     "Hacker News"
→ octo_stop_profile(uuid="tmp-456")             profile gone

The title is "Hacker News".

Round up a tagged fleet

You: List every profile tagged "ads"

→ octo_search_profiles(tags=["ads"], limit=50)
  12 profiles: ads_US_01, ads_UK_02, …

Running it elsewhere

Octo on another box? Set OCTO_HOST:

claude mcp add octobrowser-mcp \
  -e OCTO_HOST="192.168.1.100" \
  -e OCTO_USERNAME="you@email.com" \    # optional — only for cloud auto sign-in
  -e OCTO_PASSWORD="your_password" \    # optional — only for cloud auto sign-in
  -- octobrowser-mcp

Only OCTO_HOST matters here — the email and password are optional and drop out entirely if you're not using the cloud API.

ws://127.0.0.1 and ws://localhost endpoints are rehomed to your host automatically, so CDP connects across the network. You'll need port 58888 and the per-profile CDP debug ports reachable — an SSH tunnel is the safe way to expose them.

When things go sideways

Flip OCTO_LOG_LEVEL=DEBUG to watch every API request on stderr.

Hacking on it

uv sync --extra dev            # or: python -m venv .venv && pip install -e ".[dev]"

uv run ruff check src/ tests/    # lint (incl. flake8-bandit security rules)
uv run ruff format src/ tests/   # format
uv run mypy src/ tests/          # strict typing
uv run pytest                    # fast, offline

The suite feeds every Octo response through httpx.MockTransport and drives the MCP surface in-process — no running Octo Browser and no network needed. CI runs the same four gates on Python 3.10 and 3.13.

Resilience by design

A key design principle: when a launch fails, the server doesn't give up. Instead, it re-checks the running profiles on the host — the profile may have started anyway, or it may be running from a prior attempt. This recovery path keeps the tool reliable under transient network hiccups or API quirks.

Under the hood

• MCP SDK 2.x — tool schemas generated straight from the Python signatures

• Playwright — CDP browser steering

• httpx — async client for both Octo APIs

• Hatchling — build backend

Credits & license

Released under the MIT License — see LICENSE. OctoBrowser-MCP began as a rework of the MIT-licensed original octo-mcp groundwork; that copyright notice is preserved in LICENSE per the terms.

This is an independent, unofficial project — not affiliated with, sponsored by, or endorsed by Octo Browser. The Octo Browser name and logo (in assets/, from the official brand kit) are trademarks of their respective owner, used here unmodified only to identify the software this server drives.

Links

• Octo Browser — antidetect browser for multi-accounting

• Octo Browser API reference — the Postman collection this client targets

• Octo Browser docs

• Model Context Protocol — the open AI-tooling protocol

• Claude Code

Explore this project

Project page & walkthrough — Try an interactive explanation and inspect the original source and results. Browser teaching examples are distinguished from trained models.

Project visual

Pixel-art adaptation of OpenMoji octopus by OpenMoji contributors, licensed CC BY-SA 4.0. Source: OpenMoji.