Octo MCP

🚀 Octo Browser MCP Server

This is an MCP (Model Context Protocol) server designed for Octo Browser, an antidetect browser for multi - accounting. It allows AI assistants such as Claude to control Octo Browser profiles using natural language.

✨ Features

• Profile Management: Start, stop, and list Octo Browser profiles.
• Search by Name: Use the Cloud API to find profiles by name (API token required).
• One - Time Profiles: Create temporary profiles that are deleted after use.
• Browser Automation: Achieve full browser control based on Playwright 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 on 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

Getting Your API Token

1. Open Octo Browser.
2. Go to Settings → API.
3. Copy your API token.

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

💻 Usage Examples

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

Profile Search (requires API token)

Browser Connection

Navigation

Interaction

Information Extraction

JavaScript

Tab Management

💻 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. You can either:

1. Add your API token to the MCP configuration.
2. 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:

1. Make sure port 58888 is accessible.
2. The CDP port (random for each profile) must be accessible.
3. 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

This project is under the MIT License - see the LICENSE file for details.

🔗 Links

• Octo Browser
• Octo Browser API Documentation
• Model Context Protocol
• Claude Code