How do I use octo-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@octo-mcp start profile 5249 and take a screenshot of google.com" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

octo-mcp

by mazamakasa

Overview Schema Related Servers Score Discussions

Python

Remote

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: Camoufox Browser MCP

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

Open Octo Browser app
Go to Settings → API
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)

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

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mazamakasa/octo-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server