Octo Browser MCP Server

MCP (Model Context Protocol) server for Octo Browser - an antidetect browser for multi-accounting. This server enables AI assistants like Claude to control Octo Browser profiles through natural language.

Features

Profile Management: Start, stop, and list Octo Browser profiles
Search by Name: Find profiles by name using Cloud API (requires API token)
One-Time Profiles: Create temporary profiles that are deleted after use
Browser Automation: Full Playwright-based browser control via CDP
Screenshot Capture: Take screenshots of pages or elements
Multi-Tab Support: Manage multiple browser tabs
Docker Compatible: Works with Octo Browser running in Docker or remote hosts

Installation

From PyPI

pip install octo-mcp

From Source

git clone https://github.com/anthropics/octo-mcp.git
cd octo-mcp
pip install -e .

Install Playwright

playwright install chromium

Configuration

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | OCTO_HOST | Octo Browser host | No | localhost | | OCTO_PORT | Local API port | No | 58888 | | OCTO_USERNAME | Octo account email (for auto-login) | No | - | | OCTO_PASSWORD | Octo account password | No | - | | OCTO_API_TOKEN | Cloud API token (for profile search by name) | No | - |

Getting Your API Token

Open Octo Browser
Go to Settings → API
Copy your API token

The API token is only needed for searching profiles by name. Basic profile operations work without it.

Usage with Claude Code

Add the MCP Server

# Basic setup (Local API only)
claude mcp add octo-mcp -- python -m octo_mcp.server

# With authentication (recommended)
claude mcp add octo-mcp \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -- python -m octo_mcp.server

# Full setup with Cloud API (enables search by profile name)
claude mcp add octo-mcp \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -e OCTO_API_TOKEN="your_api_token" \
  -- python -m octo_mcp.server

Restart Claude Code

After adding the MCP server, restart Claude Code to load the new tools.

Available Tools

Profile Management

| Tool | Description | |------|-------------| | octo_health_check | Check if Octo Browser is running | | octo_list_profiles | List active (running) profiles | | octo_start_profile | Start a profile by UUID | | octo_stop_profile | Stop a running profile | | octo_start_one_time_profile | Create and start a temporary profile |

Profile Search (requires API token)

| Tool | Description | |------|-------------| | octo_find_profile_by_name | Find profile by exact name | | octo_start_profile_by_name | Find and start profile by name | | octo_search_profiles | Search profiles by name or tags |

Browser Connection

| Tool | Description | |------|-------------| | browser_connect | Connect to a running profile via CDP | | browser_disconnect | Disconnect from browser |

Navigation

| Tool | Description | |------|-------------| | browser_navigate | Go to URL | | browser_get_url | Get current URL | | browser_go_back | Navigate back | | browser_go_forward | Navigate forward | | browser_reload | Reload page |

Interaction

| Tool | Description | |------|-------------| | browser_click | Click element or coordinates | | browser_type | Type text into element | | browser_press_key | Press keyboard key (Enter, Tab, etc.) | | browser_scroll | Scroll page or element | | browser_hover | Hover over element | | browser_select | Select option in dropdown |

Information Extraction

| Tool | Description | |------|-------------| | browser_screenshot | Take screenshot (returns image) | | browser_get_text | Get element text content | | browser_get_html | Get page or element HTML | | browser_get_attribute | Get element attribute | | browser_query_selector_all | Find all matching elements | | browser_wait_for_selector | Wait for element to appear |

JavaScript

| Tool | Description | |------|-------------| | browser_evaluate | Execute JavaScript and return result |

Tab Management

| Tool | Description | |------|-------------| | browser_list_tabs | List open tabs | | browser_switch_tab | Switch to tab by index | | browser_new_tab | Open new tab | | browser_close_tab | Close current tab |

Example Conversation

User: Start my profile "work_account" and go to google.com

Claude: I'll start the profile and navigate to Google.

[Uses octo_start_profile_by_name with name="work_account"]
Profile 'work_account' started.
ws_endpoint: ws://localhost:52341/devtools/browser/abc123

[Uses browser_connect with the ws_endpoint]
Connected to browser.

[Uses browser_navigate with url="https://google.com"]
Navigated to https://google.com

[Uses browser_screenshot]
[Shows screenshot of Google homepage]

The profile is now running and showing Google's homepage.

Docker / Remote Setup

If Octo Browser runs on a different host (e.g., in Docker), set the OCTO_HOST variable:

claude mcp add octo-mcp \
  -e OCTO_HOST="192.168.1.100" \
  -e OCTO_USERNAME="your@email.com" \
  -e OCTO_PASSWORD="your_password" \
  -- python -m octo_mcp.server

The server automatically rewrites WebSocket URLs from 127.0.0.1 to the configured host.

Troubleshooting

"Octo Browser API unavailable"

Make sure Octo Browser is running. The Local API starts automatically when you open the application.

"OCTO_API_TOKEN is not set"

This error appears when using octo_find_profile_by_name or octo_search_profiles without an API token. Either:

Add your API token to the MCP configuration
Use octo_start_profile with UUID instead (get UUID from Octo Browser UI)

"Profile not found"

The profile name must match exactly (case-sensitive). Use octo_search_profiles to find available profiles.

WebSocket connection fails

If running Octo Browser on a different host:

Make sure port 58888 is accessible
The CDP port (random for each profile) must be accessible
Set OCTO_HOST to the correct IP address

Development

Setup

git clone https://github.com/anthropics/octo-mcp.git
cd octo-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run Tests

pytest

Code Style

ruff check .
ruff format .

License

MIT License - see LICENSE file.

MCP Servers