octo-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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 Browser MCP Server
Control antidetect browser profiles with AI through the Model Context Protocol
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 chromiumFrom PyPI (coming soon)
pip install octo-mcp
playwright install chromiumPrerequisites
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-mcp2. 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 Browser host (for remote/Docker setups) |
|
| Local API port |
|
| Account email for auto-login | -- |
| Account password for auto-login | -- |
| Cloud API token (for search, tags, proxies) | -- |
Tools Reference (34 tools)
Profile Management (Local API)
Tool | Description |
| Check Octo Browser API availability and version |
| List all active (running) profiles with their WebSocket endpoints |
| Start a profile by UUID; returns |
| Gracefully or forcefully stop a running profile |
| Create a temporary profile (auto-deleted on stop); supports OS selection |
Profile Search & Management (Cloud API)
Tool | Description |
| Find a profile by exact or partial name match |
| Find profile by name and start it (combines find + start) |
| Search profiles by name, tags, status; supports sorting and pagination |
| Get full profile data: fingerprint, proxy, extensions, tags |
Team Resources (Cloud API)
Tool | Description |
| List all team browser extensions (name, version, UUID) |
| Delete team extensions by UUID |
| List all profile tags (name, color, UUID) |
| List all saved proxies (type, host, port, UUID) |
Browser Connection
Tool | Description |
| Connect to a running profile via CDP WebSocket endpoint |
| Disconnect from browser (does not stop the Octo profile) |
Navigation
Tool | Description |
| Navigate to URL with configurable wait strategy ( |
| Get the current page URL |
| Navigate back in history |
| Navigate forward in history |
| Reload the current page |
Page Interaction
Tool | Description |
| Click by CSS selector or (x, y) coordinates; supports right-click, double-click |
| Type text into an element (via |
| Press a keyboard key ( |
| Scroll page or specific element in any direction |
| Hover over an element (useful for dropdowns and tooltips) |
| Select an option in a |
Information Extraction
Tool | Description |
| Capture screenshot of full page or specific element (returns PNG image) |
| Extract text content from an element |
| Get innerHTML or outerHTML of element, or full page HTML |
| Get any attribute value from an element |
| Find all matching elements with their tag, text, class, bounds |
| Wait for element to appear/disappear with configurable timeout |
JavaScript Execution
Tool | Description |
| Execute arbitrary JavaScript and return the result |
Tab Management
Tool | Description |
| List all open tabs with title, URL, and active status |
| Switch to a tab by index |
| Open a new tab, optionally navigating to a URL |
| 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.6Remote / 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-mcpThe 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 |
"Profile not found" | Profile names are case-sensitive. Use |
WebSocket connection fails | Check that OCTO_HOST is correct and CDP ports are accessible. |
"Browser not connected" | Call |
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
pytestTech 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
Links
Octo Browser -- Antidetect browser for multi-accounting
Model Context Protocol -- Open protocol for AI-tool integration
Available Tools
37 toolsbrowser_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_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
Scored across 37 tools
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.
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.
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.
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
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
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
- AlicenseAqualityDmaintenanceEnables browser automation with anti-detection features, including navigation, interaction, form filling, and session management.2228 PyPI10MIT
- AlicenseAqualityDmaintenanceEnables Claude Desktop to automate OctoBrowser, managing profiles, tags, proxies, and cookies through a standardized protocol interface.17MIT
- AlicenseCqualityDmaintenanceEnables AI-powered browser automation with real profiles, supporting interaction, navigation, form filling, and advanced features like visual overlays and self-healing selectors.42Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables 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.-