antidetect-browser-mcp

Standalone MCP server for controlling BitBrowser antidetect profiles via Playwright with built-in behavioral stealth.

Designed for remote browser automation — the agent (OpenCode) runs on Linux and controls BitBrowser profiles on a Windows server via HTTP.

Features

• 21 MCP tools — profile management, navigation, inspection, interaction, advanced
• Three-layer stealth — BitBrowser fingerprint + playwright-stealth + behavioral (Bezier mouse, human typing, persona-based RNG)
• chrome.runtime patch — passes bot.sannysoft.com detection
• HTTP transport — accessible remotely via direct HTTP or SSH tunnel
• Abstract browser client — BitBrowser now, Dolphin Anty / AdsPower later
• 210 unit tests + 24 live tests — 99.71% coverage

Architecture

Linux (OpenCode agent)                Windows (BitBrowser + MCP server)
┌──────────────────┐                 ┌─────────────────────────┐
│ OpenCode         │   HTTP or       │ BitBrowser API (:54529) │
│ opencode.json →  │◄───────────────►│ MCP server    (:8765)   │
│ <windows-ip>:8765│                 │ Playwright (CDP)        │
└──────────────────┘                 └─────────────────────────┘

Tools

Category	Tools
Profile	open_profile, close_profile, list_profiles
Navigation	navigate, get_url, get_title, reload, wait_for_selector, wait_for_load_state
Inspection	screenshot, get_dom, get_text
Interaction	click, hover, type_text, press_key, scroll
Advanced	execute_js, get_console_logs, get_cookies, upload_file

Stealth layers

1. BitBrowser fingerprint — hardware-level spoofing (WebGL, Canvas, Audio, WebRTC)
2. playwright-stealth — navigator.webdriver, plugins, permissions, chrome object
3. Behavioral — Bezier curve mouse movement, variable-speed typing with occasional typos and correction, persona-based deterministic RNG (same profile = same behavior)

Installation

Prerequisites

• Python 3.12+
• uv package manager
• BitBrowser running on the same machine

Setup

git clone https://github.com/slaid098/antidetect-browser-mcp.git
cd antidetect-browser-mcp
uv sync --extra dev

Configuration

Create config.json in the project root:

{
    "bitbrowser_url": "http://127.0.0.1:54529",
    "mcp_host": "127.0.0.1",
    "mcp_port": 8765
}

Field	Default	Description
bitbrowser_url	http://127.0.0.1:54529	BitBrowser local API URL (check your BitBrowser port in settings)
mcp_host	0.0.0.0	MCP server bind address. Use 127.0.0.1 for SSH-tunnel-only access
mcp_port	8765	MCP server port
api_token	""	Bearer token for authentication (optional)

Usage

Run MCP server

uv run antidetect-browser-mcp

Connect from OpenCode (Linux)

OpenCode — add to opencode.json:

{
    "mcp": {
        "antidetect-browser": {
            "type": "remote",
            "url": "http://<windows-ip>:8765/mcp",
            "enabled": true,
            "timeout": 30000
        }
    }
}

Claude Desktop — add to claude_desktop_config.json:

{
    "mcpServers": {
        "antidetect-browser": {
            "url": "http://localhost:8765"
        }
    }
}

Remote connection

Two approaches for connecting from a remote Linux server:

Option A: Direct HTTP + firewall (simpler)

Set mcp_host to 0.0.0.0 in config.json, then restrict access with a firewall rule:

# Windows Firewall: allow port 8765 only from your Linux server IP
netsh advfirewall firewall add rule name="Antidetect MCP" dir=in action=allow protocol=TCP localport=8765 remoteip=<linux-server-ip>

Point opencode directly: "url": "http://<windows-ip>:8765/mcp"

Option B: SSH tunnel (encrypted)

Set mcp_host to 127.0.0.1 in config.json, then create a tunnel:

autossh -M 0 -L 127.0.0.1:8765:localhost:8765 user@<windows-server-ip> -N -4

Point opencode to localhost: "url": "http://localhost:8765/mcp"

Note: Use -4 flag and 127.0.0.1:8765 (not just 8765) to force IPv4 only. Some container environments don't support IPv6, which causes binding failures.

Auto-start with NSSM (Windows)

nssm install antidetect-mcp "C:\path\to\uv.exe" "run antidetect-browser-mcp"
nssm set antidetect-mcp AppDirectory "C:\path\to\antidetect-browser-mcp"
nssm set antidetect-mcp Start SERVICE_AUTO_START
nssm start antidetect-mcp

Testing

# Unit tests (no BitBrowser required, 210 tests)
uv run pytest tests/unit/ -m "not live" --cov=src --cov-report=term-missing

# Live tests (requires BitBrowser at 127.0.0.1:54529, 24 tests)
uv run pytest tests/live/ -m "live" --no-cov -v

# All tests
uv run pytest --cov=src --cov-report=term-missing

Quality checks

uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/

Project structure

src/antidetect_browser_mcp/
├── server.py              # FastMCP server entry point
├── config.py              # Configuration loading
├── errors.py              # Error formatting helpers
├── browsers/
│   ├── base.py            # Abstract AntidetectBrowserClient
│   ├── models.py          # Pydantic data models
│   └── bitbrowser/        # BitBrowser implementation
│       └── client.py      # BitBrowser API client (httpx)
├── session/
│   ├── manager.py         # SessionManager (Playwright + stealth)
│   └── playwright.py      # Playwright lifecycle
├── stealth/
│   ├── persona.py         # Deterministic RNG per profile
│   ├── mouse.py           # Bezier curve mouse movement
│   ├── keyboard.py        # Human-like typing with typos
│   └── patches.py         # chrome.runtime init script
└── tools/
    ├── profiles.py        # open/close/list profiles
    ├── navigation.py      # navigate, reload, wait helpers
    ├── inspection.py      # screenshot, get_dom, get_text
    ├── interaction.py     # click, hover, type, press, scroll
    └── advanced.py        # execute_js, cookies, console, upload

Tech stack

Component	Technology
MCP framework	FastMCP (PrefectHQ)
Browser automation	Playwright (CDP connection)
Stealth	playwright-stealth + custom patches
HTTP client	httpx
Validation	Pydantic v2
Logging	Loguru
Testing	pytest, pytest-asyncio, pytest-cov
Linting	ruff (strict), mypy (strict)

License

MIT