# antidetect-browser-mcp

Standalone MCP server for controlling [BitBrowser](https://bitbrowser.cn) antidetect profiles
via [Playwright](https://playwright.dev) 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, works through 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         │   SSH tunnel    │ BitBrowser API (:54529) │
│ opencode.json →  │◄──────────────►│ MCP server    (:8765)   │
│ localhost: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](https://docs.astral.sh/uv/) package manager
- [BitBrowser](https://bitbrowser.cn) running on the same machine

### Setup

```bash
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:

```json
{
    "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 |
| `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

```bash
uv run antidetect-browser-mcp
```

### Connect from OpenCode (Linux)

Add to `opencode.json`:

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

For remote access, set up an SSH tunnel:

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

### Auto-start with NSSM (Windows)

```powershell
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

```bash
# 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

```bash
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](https://github.com/jlowin/fastmcp) (PrefectHQ) |
| Browser automation | [Playwright](https://playwright.dev) (CDP connection) |
| Stealth | [playwright-stealth](https://github.com/Mattwmaster58/playwright_stealth) + custom patches |
| HTTP client | [httpx](https://www.python-httpx.org) |
| Validation | [Pydantic](https://docs.pydantic.dev) v2 |
| Logging | [Loguru](https://loguru.readthedocs.io) |
| Testing | pytest, pytest-asyncio, pytest-cov |
| Linting | ruff (strict), mypy (strict) |

## License

MIT