# Antibrowser MCP

A stdio MCP server built on [cloakbrowser](https://pypi.org/project/cloakbrowser/) (stealth Chromium) that lets LLM agents open web pages and interact with them via a browser-use-style accessibility tree with numeric indices — keeping token usage low.

## Features

- Persistent user profile at `$HOME/.antibrowser/data-dir` (cookies, localStorage, cache survive restarts).
- Accessibility-tree snapshot: LLM receives an indexed text like `[1] button "Submit"` and calls `click(1)`.
- Default headless; flip to headed at runtime via `set_headed(true)` for debugging — profile state survives.
- 12 tools: `navigate`, `snapshot`, `click`, `fill`, `press`, `scroll`, `get_text`, `back`, `forward`, `set_headed`, `set_humanize`, `close`.

## Installation

```bash
git clone <this-repo>
cd anti-browser-mcp
uv sync
```

cloakbrowser downloads its patched Chromium on first launch; if that fails, run:

```bash
uv run python -c "import cloakbrowser; cloakbrowser.ensure_binary()"
```

## Configuration

| Env var | Default | Meaning |
|---|---|---|
| `ANTIBROWSER_DATA_DIR` | `~/.antibrowser/data-dir` | Browser profile directory |
| `ANTIBROWSER_HEADLESS` | `1` | `0` launches headed by default |
| `ANTIBROWSER_NAV_TIMEOUT_MS` | `30000` | Navigation timeout |
| `ANTIBROWSER_LICENSE_KEY` | unset | cloakbrowser license key (if required by your plan) |
| `ANTIBROWSER_PROXY` | unset | Proxy URL |
| `ANTIBROWSER_HUMANIZE` | `0` | `1` enables cloakbrowser's human-like mouse/keyboard/scroll layer by default |

## Wiring into Claude Code

```bash
claude mcp add antibrowser -- uv --directory /path/to/anti-browser-mcp run anti-browser-mcp
```

## Wiring into Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "antibrowser": {
      "command": "uv",
      "args": ["--directory", "/path/to/anti-browser-mcp", "run", "anti-browser-mcp"]
    }
  }
}
```

## Usage example (in Claude)

> Open example.com and tell me the main heading.

Claude will call `navigate`, then `snapshot`, then `get_text(1)` (or whichever index the heading got) and reply.

## Manual login CLI

Before letting the LLM drive the browser, you usually need to log in to sites once. The `antibrowser open` command launches cloakbrowser in headed mode against the same profile the MCP server uses.

```bash
uv run antibrowser open https://github.com https://mail.google.com
```

A browser window opens. Log in to each site. When done, return to the terminal and press Enter — the browser closes and cookies/localStorage are persisted to your profile at `~/.antibrowser/data-dir` (or `$ANTIBROWSER_DATA_DIR`).

Pass `--humanize` to enable cloakbrowser's human-like input layer (slower, randomized mouse/keyboard) — useful for sites with strict bot detection:

```bash
uv run antibrowser open --humanize https://github.com
```

Now when the LLM (via the MCP server) calls `navigate https://github.com`, the session is already authenticated.

### Profile is locked

If you see:

```
Error: profile at ... is locked. Is the antibrowser MCP server or another 'antibrowser open' running? Close it first.
```

it means another process is using the profile. Chromium only allows one process per profile directory. Stop the MCP server (or close the other `antibrowser open` session) and retry.

### Installed script

After `uv sync`, the entry `antibrowser` is installed into the venv. On Windows call it directly:

```powershell
D:\path\to\anti-browser-mcp\.venv\Scripts\antibrowser.exe open https://github.com
```

## Development

```bash
uv run pytest -q                          # all tests
uv run pytest tests/test_config.py -v     # unit only
uv run pytest -k "not persistence" -v     # skip slow persistence tests
```

All unit and integration tests are expected to pass locally.