Skip to main content
Glama

Octo Browser MCP Server

Control antidetect browser profiles with AI through the Model Context Protocol

Python 3.10+ MCP License: MIT Octo Browser Playwright

Installation · Quick Start · Tools Reference · Examples · Architecture


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.

Related MCP server: OctoBrowser MCP Server

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="your@email.com" \
  -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": "your@email.com",
        "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

Variable

Description

Default

OCTO_HOST

Octo Browser host (for remote/Docker setups)

localhost

OCTO_PORT

Local API port

58888

OCTO_USERNAME

Account email for auto-login

--

OCTO_PASSWORD

Account password for auto-login

--

OCTO_API_TOKEN

Cloud API token (for search, tags, proxies)

--

Tools Reference (34 tools)

Profile Management (Local API)

Tool

Description

octo_health_check

Check Octo Browser API availability and version

octo_list_profiles

List all active (running) profiles with their WebSocket endpoints

octo_start_profile

Start a profile by UUID; returns ws_endpoint for CDP connection

octo_stop_profile

Gracefully or forcefully stop a running profile

octo_start_one_time_profile

Create a temporary profile (auto-deleted on stop); supports OS selection

Profile Search & Management (Cloud API)

Tool

Description

octo_find_profile_by_name

Find a profile by exact or partial name match

octo_start_profile_by_name

Find profile by name and start it (combines find + start)

octo_search_profiles

Search profiles by name, tags, status; supports sorting and pagination

octo_get_profile

Get full profile data: fingerprint, proxy, extensions, tags

Team Resources (Cloud API)

Tool

Description

octo_get_extensions

List all team browser extensions (name, version, UUID)

octo_delete_extensions

Delete team extensions by UUID

octo_get_tags

List all profile tags (name, color, UUID)

octo_get_proxies

List all saved proxies (type, host, port, UUID)

Browser Connection

Tool

Description

browser_connect

Connect to a running profile via CDP WebSocket endpoint

browser_disconnect

Disconnect from browser (does not stop the Octo profile)

Navigation

Tool

Description

browser_navigate

Navigate to URL with configurable wait strategy (load, domcontentloaded, networkidle)

browser_get_url

Get the current page URL

browser_go_back

Navigate back in history

browser_go_forward

Navigate forward in history

browser_reload

Reload the current page

Page Interaction

Tool

Description

browser_click

Click by CSS selector or (x, y) coordinates; supports right-click, double-click

browser_type

Type text into an element (via fill) or simulate keystrokes with delay

browser_press_key

Press a keyboard key (Enter, Tab, Escape, ArrowDown, etc.)

browser_scroll

Scroll page or specific element in any direction

browser_hover

Hover over an element (useful for dropdowns and tooltips)

browser_select

Select an option in a <select> dropdown

Information Extraction

Tool

Description

browser_screenshot

Capture screenshot of full page or specific element (returns PNG image)

browser_get_text

Extract text content from an element

browser_get_html

Get innerHTML or outerHTML of element, or full page HTML

browser_get_attribute

Get any attribute value from an element

browser_query_selector_all

Find all matching elements with their tag, text, class, bounds

browser_wait_for_selector

Wait for element to appear/disappear with configurable timeout

JavaScript Execution

Tool

Description

browser_evaluate

Execute arbitrary JavaScript and return the result

Tab Management

Tool

Description

browser_list_tabs

List all open tabs with title, URL, and active status

browser_switch_tab

Switch to a tab by index

browser_new_tab

Open a new tab, optionally navigating to a URL

browser_close_tab

Close the current tab

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="your@email.com" \
  -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

Problem

Solution

"Octo Browser API unavailable"

Make sure Octo Browser is running. The Local API starts with the app.

"OCTO_API_TOKEN is not set"

Add your API token or use octo_start_profile with UUID directly.

"Profile not found"

Profile names are case-sensitive. Use octo_search_profiles to browse.

WebSocket connection fails

Check that OCTO_HOST is correct and CDP ports are accessible.

"Browser not connected"

Call browser_connect with the ws_endpoint from profile start.

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 -- Model Context Protocol server framework

  • Playwright -- Browser automation via CDP (Chrome DevTools Protocol)

  • httpx -- Async HTTP client for Octo Browser APIs

  • Hatchling -- Modern Python build system

License

MIT License -- see LICENSE for details.

Author

Maksym Babenko -- GitHub · Telegram

Available Tools

37 tools
browser_clickA

Click on an element. Specify a CSS selector or coordinates.

Inputs: x, y, button, selector, +1 more.

browser_close_tabA

Close the current tab.

Inputs: no named parameters.

browser_connectA

Connect to a running Octo Browser profile via CDP. Must be called after octo_start_profile.

Inputs: ws_endpoint (required).

browser_disconnectA

Disconnect from browser (does not stop the Octo profile).

Inputs: no named parameters.

browser_evaluateB

Execute JavaScript code on the page and return the result.

Inputs: script (required).

browser_get_attributeB

Get an attribute of an element.

Inputs: selector (required), attribute (required).

browser_get_htmlA

Get HTML content of the page or an element.

Inputs: outer, selector.

browser_get_textB

Get text content of an element.

Inputs: selector (required).

browser_get_urlA

Get the current page URL.

Inputs: no named parameters.

browser_go_backA

Go back to the previous page.

Inputs: no named parameters.

browser_go_forwardA

Go forward to the next page.

Inputs: no named parameters.

browser_hoverB

Hover over an element.

Inputs: selector (required).

browser_list_tabsA

Get list of open tabs.

Inputs: no named parameters.

browser_navigateB

Navigate to the specified URL in the browser.

Inputs: url (required), wait_until.

browser_new_tabB

Open a new tab.

Inputs: url.

browser_press_keyB

Press a keyboard key (Enter, Tab, Escape, etc.)

Inputs: key (required).

browser_query_selector_allB

Find all elements by selector and return their information.

Inputs: selector (required).

browser_reloadA

Reload the current page.

Inputs: no named parameters.

browser_screenshotA

Take a screenshot of the page or an element. Returns an image.

Inputs: selector, full_page.

browser_scrollC

Scroll the page.

Inputs: amount, selector, direction.

browser_selectB

Select an option in a select element.

Inputs: value (required), selector (required).

browser_switch_tabC

Switch to another tab.

Inputs: index (required).

browser_typeC

Type text into an element or on the page.

Inputs: text (required), delay, selector.

browser_wait_for_selectorB

Wait for an element to appear on the page.

Inputs: selector (required), state, timeout.

octo_delete_extensionsB

Delete team extensions by UUID.

Inputs: uuids (required).

octo_find_profile_by_nameB

Find an Octo Browser profile by name (title). Uses Cloud API. Requires OCTO_API_TOKEN.

Inputs: name (required), exact_match.

octo_get_extensionsA

Get list of team extensions. Shows name, version, uuid of each extension.

Inputs: no named parameters.

octo_get_profileA

Get full profile data by UUID: fingerprint, proxy, extensions, description, tags. Uses Cloud API.

Inputs: uuid (required).

octo_get_proxiesA

Get list of all proxies. Shows type, host, port, uuid of each proxy.

Inputs: no named parameters.

octo_get_tagsA

Get list of all tags. Shows name, color, uuid of each tag.

Inputs: no named parameters.

octo_health_checkA

Check Octo Browser API availability. Call this first to verify connectivity.

Inputs: no named parameters.

octo_list_profilesA

Get list of active (running) Octo Browser profiles. Shows UUID, name, and ws_endpoint for each profile.

Inputs: no named parameters.

octo_search_profilesC

Search profiles by partial name or tags. Uses Cloud API. Requires OCTO_API_TOKEN.

Inputs: tags, limit, search, status, +1 more.

octo_start_one_time_profileA

Create and start a one-time (temporary) Octo Browser profile. Profile is deleted after stopping. Faster than regular profiles, ideal for scraping.

Inputs: os, headless.

octo_start_profileA

Start an Octo Browser profile by UUID. Returns ws_endpoint for CDP connection. If already running, returns existing data.

Inputs: uuid (required), headless.

octo_start_profile_by_nameA

Find a profile by name and start it. Combines find + start. Requires OCTO_API_TOKEN.

Inputs: name (required), headless.

octo_stop_profileB

Stop an Octo Browser profile by UUID.

Inputs: uuid (required), force.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 37 tools

    Disambiguation4/5

    Most tools have distinct purposes, especially the browser automation ones. However, the profile management tools like list_profiles, search_profiles, find_profile_by_name, and get_profile are similar and could cause confusion, as could start_profile and start_profile_by_name.

    Naming Consistency3/5

    The tool names follow a snake_case format but mix two prefixes (octo_ and browser_) and inconsistent verb choices within the octo_ group (list, get, search, find, start, stop, delete). Some names deviate from verb_noun patterns, like octo_health_check and browser_query_selector_all, making the set readable but not fully predictable.

    Tool Count2/5

    With 37 tools, this is well above the 25-tool threshold for a heavy set. While the browser automation tools are numerous and justified, the profile management tools include several redundant lookups and start methods that could be consolidated to reduce the count.

    Completeness3/5

    The browser automation surface is fairly complete with navigation, interaction, content extraction, and tab management. However, the profile management is incomplete: there is no create, update, or delete for persistent profiles, and extensions, tags, and proxies only support limited read/delete operations.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    • EmailOctopus MCP server for ChatGPT, Claude and any AI agent: list campaigns, get campaign report, duplicate campaign, create segment, set campaign recipients, schedule campaign, send campaign and unsubscribe contacts in your own EmailOctopus account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to EmailOctopus yourself; Cotlet does not store your password and you need no EmailOctopus API key. About the official EmailOctopus API: EmailOctopus has a public REST API (v2) for lists, contacts, fields, tags, campaign reports and starting an automation for a contact, but no official MCP server and no API for creating, scheduling or sending a campaign (checked 20 Oct 2026). EmailOctopus states that it does not support API sending: all emails need to be created directly in the Dashboard. Setup and FAQ: https://cotlet.dev/integrations/emailoctopus-api-mcp-server

    • Privy MCP server for ChatGPT, Claude and any AI agent: list campaigns, create segment, duplicate campaign, create email campaign, send or schedule campaign, pause display, launch display and tag contacts in your own Privy account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Privy yourself; Cotlet does not store your password and you need no Privy API key. About the official Privy API: Privy has a public API on paid plans and a read-only MCP server (checked 23 Oct 2026). The API reads contacts, campaigns, flows, displays, segments, coupons, orders and reports, and writes contacts, order events and custom events. Setup and FAQ: https://cotlet.dev/integrations/privy-api-mcp-server

      https://cotlet.dev/mcp/v1/privy
    • Buildium MCP server for ChatGPT, Claude and any AI agent: record lease payment, list outstanding balances, send text message, create task, add work order and send announcement in your own Buildium account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Buildium yourself; Cotlet does not store your password and you need no Buildium API key. About the official Buildium API: Yes, Buildium has an official REST API, the Open API, but only on the Premium plan (checked 27 Oct 2026). Buildium's developer guide says "To take advantage of the Buildium Open API you must have a Premium Subscription", and an administrator has to switch it on under Settings > Application settings > Api settings before anyone can create a key. Setup and FAQ: https://cotlet.dev/integrations/buildium-api-mcp-server

    • Breezeway MCP server for ChatGPT, Claude and any AI agent: list tasks, create task, assign task, add task comment, close task, approve task, reopen task and read task checklist in your own Breezeway account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Breezeway yourself; Cotlet does not store your password and you need no Breezeway API key. About the official Breezeway API: Breezeway has a REST API for properties, reservations, tasks and people, but you need API keys from a request form, and it has no official MCP server (checked 20 Oct 2026). Templates, task tags, subdepartments and supplies can only be created in the app. Setup and FAQ: https://cotlet.dev/integrations/breezeway-api-mcp-server

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables browser automation with anti-detection features, including navigation, interaction, form filling, and session management.
      22
      28 PyPI
      10
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI-powered browser automation with real profiles, supporting interaction, navigation, form filling, and advanced features like visual overlays and self-healing selectors.
      42
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to control Multilogin X anti-detect browser profiles via a streamable HTTP MCP interface. Supports profile management, session handling, and a broad catalog of browser actions such as navigation, clicking, typing, screenshots, and more.
      -