cloak-browser-mcp

# cloak-browser-mcp

A Model Context Protocol (MCP) server backed by [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser) — a source-patched Chromium that passes Cloudflare Turnstile, reCAPTCHA v3, FingerprintJS, BrowserScan, and 30+ other bot detection services without runtime JS injection.

Drop-in replacement for `@playwright/mcp` with **86 tools**: every Playwright MCP tool except `browser_annotate` (see [Not implemented](#not-implemented)), plus a Cloak-exclusive stealth/profile/audit layer.

> Works with Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, or any MCP client.

---

## Table of contents

- [Why CloakBrowser over vanilla Playwright?](#why-cloakbrowser-over-vanilla-playwright)
- [Quick start](#quick-start)
- [Capabilities (`--caps`)](#capabilities---caps)
- [CloakBrowser-exclusive tools](#cloakbrowser-exclusive-tools-always-on)
- [CLI flags](#cli-flags)
- [Tool inventory](#tool-inventory)
- [Target syntax for interaction tools](#target-syntax-for-interaction-tools)
- [Example flows](#example-flows)
- [Security model](#security-model)
- [Changelog](#changelog)
- [License](#license)

---

## Why CloakBrowser over vanilla Playwright?

| | `@playwright/mcp` | `cloak-browser-mcp` |
|---|---|---|
| Chromium | Stock | Source-patched (58 C++ patches) |
| `navigator.webdriver` | `true` (leaks) | absent |
| Cloudflare Turnstile | Fails | Auto-pass |
| reCAPTCHA v3 score | ~0.1 | ~0.9 |
| Humanized mouse / keyboard | None | Bézier curves, typo correction |
| Persistent profiles | Manual | First-class CLI flag + management tools |
| GeoIP-aware emulation | None | Auto timezone/locale from proxy exit IP |
| Stealth audit / detection probe | None | Built-in `cloak_stealth_audit` + `cloak_detection_test` |

When you don't need stealth, `@playwright/mcp` is faster and lighter — use that. When the site has any bot detection (Cloudflare, DataDome, PerimeterX, FingerprintJS) — use this.

---

## Quick start

### 1. Install once

The wrapper installs from npm; the CloakBrowser Chromium binary (~200 MB) downloads on first use into `~/.cloakbrowser/`.

Requires Node.js `^20.19.0 || >=22.12.0` (the minimum CloakBrowser itself needs).

The binary comes in two tiers. Without a key you get the free binary. Set `CLOAKBROWSER_LICENSE_KEY` in the MCP server's environment to use a CloakBrowser Pro license; `CLOAKBROWSER_RELEASE_CHANNEL` (`stable` or `preview`) and `CLOAKBROWSER_VERSION` are read by the CloakBrowser library too. See [cloakbrowser.dev](https://cloakbrowser.dev) for what each tier includes. `cloak_binary_info` reports the active tier.

```bash
npm install -g @devinwangd/cloak-browser-mcp
```

Or run on demand without installing:

```bash
npx @devinwangd/cloak-browser-mcp --caps all
```

After install, the binary on `PATH` is `cloak-browser-mcp` (unscoped) — that's what you reference in MCP client configs below.

### 2. Wire into your MCP client

#### Claude Code (`~/.claude.json` or project `.mcp.json`)

```json
{
  "mcpServers": {
    "cloak-browser": {
      "command": "cloak-browser-mcp",
      "args": ["--caps", "all"]
    }
  }
}
```

#### Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)

```json
{
  "servers": {
    "cloak-browser": {
      "command": "cloak-browser-mcp",
      "args": ["--caps", "all"]
    }
  }
}
```

#### Persistent profile + proxy + humanized inputs

```json
{
  "mcpServers": {
    "cloak-browser": {
      "command": "cloak-browser-mcp",
      "args": [
        "--caps", "all",
        "--profile-dir", "/Users/me/.cloak-browser-mcp/profiles/work",
        "--proxy", "http://user:pass@proxy.example.com:8080",
        "--timezone", "Europe/London",
        "--locale", "en-GB",
        "--geoip",
        "--humanize",
        "--viewport", "1920x1080",
        "--allowed-domains", "*.example.com,*.cloudflare.com"
      ]
    }
  }
}
```

### 3. Use it

In Claude Code:

> "Open example.com, click the search box, search for 'hello', take a screenshot."

The agent will call `browser_navigate` → `browser_snapshot` → `browser_click` → `browser_type` → `browser_take_screenshot`.

---

## Capabilities (`--caps`)

| Cap | Tools | Use when |
|---|---|---|
| (always) | navigation, interaction, page state | Standard browsing |
| `network` | request inspection, route mocking, offline simulation | Debugging APIs, testing failure modes |
| `storage` | cookies, localStorage, sessionStorage, storage state export/import | Auth state persistence, session replay |
| `vision` | pixel-coordinate mouse | Bypassing accessibility tree for canvas / SVG apps |
| `pdf` | `browser_pdf_save` | Snapshotting pages as PDF |
| `testing` | `verify_*` + `generate_locator` | Codegen for Playwright tests |
| `devtools` | highlight, tracing, video, resume | Debugging agent decisions |
| `config` | `get_config`, `close`, `run_code_unsafe` | Introspection + (with `--enable-unsafe-eval`) arbitrary JS |
| `humanize` | `cloak_humanize_set` | Tuning humanized input parameters |

`--caps all` enables everything (except `run_code_unsafe`, which additionally requires `--enable-unsafe-eval`).

---

## CloakBrowser-exclusive tools (always on)

| Tool | Purpose |
|---|---|
| `cloak_set_fingerprint` | Override canvas seed, GPU vendor/renderer, screen size, hardware concurrency, device memory, UA brand, platform, storage quota |
| `cloak_set_timezone` | Live timezone via CDP (no relaunch) |
| `cloak_set_locale` | Override `navigator.language` and `Accept-Language` |
| `cloak_set_geolocation` | Set coords, or auto-resolve from proxy exit IP |
| `cloak_set_proxy` | Switch proxy mid-session |
| `cloak_detection_test` | Load a known probe (CreepJS, FingerprintJS, BrowserScan, SannySoft, Cloudflare Turnstile) and dump results |
| `cloak_stealth_audit` | Programmatic check: `navigator.webdriver`, plugin count, WebGL vendor, languages, UA, chrome.runtime, canvas hash, `$cdc_*` CDP signals |
| `cloak_request_signal_inspect` | Capture per-request TLS / header signals for a single URL |
| `cloak_persistent_profile_create` / `list` / `delete` | Manage `~/.cloak-browser-mcp/profiles/` |
| `cloak_binary_info` / `cloak_binary_update` | Inspect / refresh the CloakBrowser Chromium binary |

---

## CLI flags

| Flag | Value | Default | Notes |
|---|---|---|---|
| `--caps <csv>` | `all` or any subset | (none) | Enables capability-gated tools |
| `--profile-dir <path>` | Absolute path | (ephemeral) | Persistent user-data dir |
| `--headless` / `--headed` | (boolean) | **headed (visible)** | Pass `--headless` for batch/CI runs. |
| `--proxy <url>` | http(s)/socks5 with inline auth | none | |
| `--timezone <tz>` | IANA tz | system | e.g. `America/New_York` |
| `--locale <bcp47>` | BCP-47 | system | e.g. `en-US` |
| `--user-agent <ua>` | string | (cloak default) | |
| `--viewport <WxH>` | e.g. `1920x1080` | 1280×720 | |
| `--geoip` | boolean | off | Auto resolve geolocation from proxy IP |
| `--humanize` | boolean | off | Enable Bézier mouse + typo-correcting keyboard |
| `--fingerprint-seed <int>` | int | random | Deterministic canvas/WebGL noise |
| `--allowed-domains <csv>` | host patterns | (open) | Whitelist for `browser_navigate` |
| `--blocked-domains <csv>` | host patterns | (none) | Blocklist for `browser_navigate` |
| `--enable-unsafe-eval` | boolean | off | Required for `browser_run_code_unsafe` |
| `--upload-allow-dir <path>` | path | (none) | Restrict file-upload source paths |
| `--download-dir <path>` | path | (cwd) | Where downloaded files land |
| `--max-pages <n>` | int | 20 | Concurrent tab cap |
| `--self-test` | boolean | off | Print the tool list and exit |

---

## Tool inventory

Tools are grouped by capability. The "always-on" sections are exposed regardless of `--caps`; capability-gated sections require the matching `--caps` entry.

### Always-on

#### Navigation

| Tool | Required | Optional | Notes |
|---|---|---|---|
| `browser_navigate` | `url` | `waitUntil`, `timeoutMs` | Subject to `--allowed-domains` / `--blocked-domains`. Returns a fresh `[eN]` snapshot. |
| `browser_navigate_back` | — | — | History back in the active tab. |
| `browser_tabs` | `action` (`list`/`new`/`switch`/`close`) | `index`, `id`, `url` | Manage tabs by id (`t1`,…) or 0-based index. |

#### Interaction

| Tool | Required | Optional | Notes |
|---|---|---|---|
| `browser_click` | `target` | `element`, `doubleClick`, `button`, `modifiers` | `target` is a `eN` ref or a Playwright selector. |
| `browser_type` | `target`, `text` | `element`, `submit`, `slowly` | `slowly:true` triggers per-character typing; combine with `--humanize`. |
| `browser_hover` | `target` | `element` | |
| `browser_drag` | `startTarget`, `endTarget` | `startElement`, `endElement` | |
| `browser_drop` | `target` | `paths`, `data` | File paths via `setInputFiles`; arbitrary MIME data via synthetic DataTransfer. |
| `browser_select_option` | `target`, `values` | `element` | |
| `browser_press_key` | `key` | — | Page-level key press (e.g. `Control+A`, `ArrowDown`). |
| `browser_handle_dialog` | `accept` | `promptText` | Responds to the most recently captured dialog. |
| `browser_file_upload` | `paths` | — | Paths constrained by `--upload-allow-dir` if set. |
| `browser_fill_form` | `fields` | — | Each field has `target` + `value` (+ optional `kind`). |
| `browser_scroll` | — | `target`, `direction`, `amount` | Element-scoped or page-level. |

#### Page state

| Tool | Required | Optional | Notes |
|---|---|---|---|
| `browser_snapshot` | — | — | Accessibility tree with `[eN]` refs for interactable nodes. |
| `browser_find` | `text` or `regex` | `filename` | Searches the snapshot instead of returning all of it. Each match is shown under its path from the root with a few lines of context, up to 20 matches. `regex` is case-sensitive unless written as `/pattern/i`. |
| `browser_emulate_media` | — | `colorScheme`, `reducedMotion`, `forcedColors`, `contrast`, `media` | Omitted parameters are left unchanged; `null` clears an override back to the system setting. |
|