CloakMCP

CloakBrowser MCP

Stealth browser automation for AI agents — a Model Context Protocol server combining CloakBrowser's anti-detection with Playwright MCP-inspired architecture.

CloakBrowser is a source-level patched Chromium that passes Cloudflare Turnstile, reCAPTCHA v3 (0.9 score), FingerprintJS, BrowserScan, and 30+ bot detection services.

Why CloakBrowser MCP?

Quick Start

Install

pip install cloakbrowsermcp

Use with Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "cloakbrowser": { "command": "cloakbrowsermcp" } } }

Use with VS Code / Cursor

Add to .vscode/mcp.json:

{

"servers": { "cloakbrowser": { "command": "cloakbrowsermcp", "args": ["--caps", "all"] } } }

Use with Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:

cloakbrowser: command: cloakbrowsermcp args: ["--caps", "all"] timeout: 120

How It Works

Snapshot-First Architecture

CloakBrowser MCP uses accessibility tree snapshots as the primary way for AI models to understand web pages — not screenshots, not raw HTML.

1. cloak_launch()           → Start stealth browser

1. cloak_navigate(pid, url) → Go to page (auto-waits for settle)
2. cloak_snapshot(pid) → Get interactive elements with [@eN] refs
3. cloak_click(pid, '@e5') → Click element by ref
4. cloak_type(pid, '@e3', 'hello') → Type into input
5. cloak_read_page(pid) → Get content as clean markdown
6. cloak_close() → Done

Each interactive element gets a [@eN] ref ID. All interaction tools use these refs — no CSS selectors needed.

Three Ways to See a Page

1. `cloak_snapshot()` — Accessibility tree with [@eN] refs. Fast, cheap, reliable. Use this.
2. `cloak_read_page()` — Clean markdown extraction. For reading content, not interacting.
3. `cloak_screenshot()` — Annotated screenshot with element indices. For visual context (images, charts, CAPTCHAs).

Stealth by Default

All anti-detection features are ON by default:

• Source-patched Chromium binary (not Playwright patches — actual Chromium source modifications)
• Human-like mouse curves, keyboard timing, and scroll patterns (humanize=True)
• Stealth fingerprint arguments (consistent canvas, WebGL, audio fingerprints)
• Proxy support with GeoIP-based timezone/locale detection

Tools

Core Tools (20 — always available)

Capability-Gated Tools (enabled via --caps)

Enable with cloakbrowsermcp --caps network,cookies,pdf,console or --caps all.

Configuration

CLI Options

cloakbrowsermcp [--caps CAPS] [--transport {stdio,sse}] [--port PORT]

• --caps: Comma-separated capabilities: network, cookies, pdf, console, all
• --transport: MCP transport — stdio (default) or sse
• --port: Port for SSE transport (default: 8931)

Environment Variables

Launch Options

cloak_launch(

headless=True, # False for headed mode (some sites require it) proxy="http://...", # Residential proxy recommended humanize=True, # Human-like input (ON by default) stealth_args=True, # Stealth fingerprints (ON by default) timezone="America/New_York", locale="en-US", geoip=False, # Auto-detect from proxy IP fingerprint_seed="my-identity", # Consistent fingerprint across sessions user_data_dir="/path", # Persistent profile )

Backend note: SessionConfig.backend is deprecated. CloakBrowser 0.4.0

removed the patchright backend (it broke proxy auth and add_init_script

without improving stealth), so current versions ignore the setting and log a

one-time warning. If you still need it, pip install "cloakbrowsermcp[patchright]"

pins cloakbrowser<0.4, where the old backend still works, but it carries

those upstream bugs.

Architecture

cloakbrowsermcp/

├── server.py # FastMCP server, tool registration, error handling ├── session.py # Browser lifecycle, page management, ref storage ├── snapshot.py # Accessibility tree JS, ref resolution ├── markdown.py # Readability-style HTML-to-markdown extraction ├── vision.py # Annotated screenshots with element indices ├── waiting.py # Smart wait, page settle, retry logic ├── stealth.py # Stealth config inspection ├── network.py # Network intercept, cookies (capability-gated) ├── init.py └── main.py

Design Principles

1. Snapshot-first — Tool descriptions steer models to use cloak_snapshot() as the primary page understanding tool
2. Ref-based only — No CSS selector tools. All interaction via [@eN] refs from snapshots
3. Stealth by default — Anti-detection, humanization, and stealth args all ON without configuration
4. Auto-snapshot after actions — Click, type, navigate all return an updated snapshot
5. Smart waiting — Auto-wait on navigation (networkidle + MutationObserver settle), auto-retry on failed clicks
6. Capability gating — Advanced tools (network, cookies, PDF) off by default to keep tool count low
7. Clean content extraction — Markdown for reading, snapshot for interaction, annotated screenshots for vision

Development

git clone https://github.com/overtimepog/CloakMCP

cd CloakMCP pip install -e ".[dev]" pytest

License

Apache-2.0