Skip to main content
Glama
cloakbrowser-mcp

cloakbrowser-mcp

by ColorSource

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?

Feature

Playwright MCP

CloakBrowser MCP

Anti-detection

❌ None

✅ Source-patched Chromium

Cloudflare bypass

❌

✅

reCAPTCHA v3

❌

✅ 0.9 score

Snapshot-first

✅

✅

Markdown extraction

❌

✅ Readability-style

Annotated screenshots

❌

✅ browser-use style

Smart page settling

Basic

✅ MutationObserver + networkidle

Auto-retry clicks

❌

✅

Humanized input

❌

✅ Mouse curves, keyboard timing

Capability gating

✅ --caps

✅ --caps

Related MCP server: Fortress MCP Server

Quick Start

Install

pip install cloakbrowser-mcp

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "cloakbrowser-mcp"
    }
  }
}

Use with VS Code / Cursor

Add to .vscode/mcp.json:

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

Use with Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  cloakbrowser:
    command: cloakbrowser-mcp
    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. browser_launch()           → Start stealth browser
2. browser_navigate(pid, url) → Go to page (auto-waits for settle)
3. browser_snapshot(pid)      → Get interactive elements with [@eN] refs
4. browser_click(pid, '@e5')  → Click element by ref
5. browser_type(pid, '@e3', 'hello')  → Type into input
6. browser_read_page(pid)     → Get content as clean markdown
7. browser_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. browser_snapshot() — Accessibility tree with [@eN] refs. Fast, cheap, reliable. Use this.

  2. browser_read_page() — Clean markdown extraction. For reading content, not interacting.

  3. browser_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 (25 — always available)

Tool

Description

browser_launch

Start stealth browser (all anti-detection ON)

browser_close

Close browser and release resources

browser_snapshot

PRIMARY — accessibility tree with [@eN] refs

browser_click

Click element by ref (auto-retry)

browser_type

Humanized type into input by ref

browser_select

Select dropdown option by ref

browser_hover

Hover over element by ref

browser_drag

Humanized drag from one ref to another

browser_check

Check/uncheck checkbox by ref

browser_read_page

Page content as clean markdown

browser_extract_links

Extract page links as structured JSON

browser_get_images

Extract page images as structured JSON

browser_screenshot

Annotated screenshot with element indices

browser_navigate

Go to URL (auto-waits for settle)

browser_back

Navigate back in history

browser_forward

Navigate forward in history

browser_press_key

Press keyboard key

browser_scroll

Scroll page up/down

browser_wait

Wait for page to settle

browser_wait_for_text

Wait for page text to appear

browser_wait_for_ref

Wait for an element ref state

browser_evaluate

Execute JavaScript in page

browser_new_page

Open new page/tab

browser_list_pages

List all open pages

browser_close_page

Close a specific page

Capability-Gated Tools (enabled via --caps)

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

Tool

Capability

Description

browser_network_intercept

network

Block/mock/passthrough requests

browser_network_continue

network

Remove interception rule

browser_get_cookies

cookies

Get all cookies

browser_set_cookies

cookies

Set cookies

browser_pdf

pdf

Save page as PDF

browser_console

console

Get browser console output

Configuration

CLI Options

cloakbrowser-mcp [--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

Variable

Default

Description

CLOAKBROWSER_LOG_LEVEL

INFO

Log level

CLOAKBROWSER_LOG_FILE

~/.cloakbrowser/logs/server.log

Log file path

CLOAKBROWSER_LOG_STDERR

false

Also log to stderr

Launch Options

browser_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
)

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 browser_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

Available Tools

28 tools
browser_backA

Navigate back in browser history. Returns an updated snapshot.

Args: page_id: Target page ID.

Inputs: page_id (required). Returns: object

browser_checkA

Check or uncheck a checkbox/radio by ref ID. Returns an updated snapshot.

Args: page_id: Target page ID. ref: Ref ID from snapshot. checked: True to check, False to uncheck.

Inputs: page_id (required), ref (required), checked. Returns: object

browser_clickA

Click an element by its [@eN] ref ID from browser_snapshot.

Auto-retries once if the element moved. Returns an updated snapshot.

Args: page_id: Target page ID. ref: Ref ID from snapshot (e.g. '@e5' or 'e5').

Inputs: page_id (required), ref (required). Returns: object

browser_closeA

Close the stealth browser and release all resources. Always call when done.

Inputs: no named parameters. Returns: object

browser_close_pageC

Close a specific page by ID.

Args: page_id: Page ID to close.

Inputs: page_id (required). Returns: object

browser_consoleA

Get browser console output (log/warn/error/info) and JS errors.

Args: page_id: Target page ID. clear: Clear the message buffer after reading.

Inputs: page_id (required), clear. Returns: object

browser_downloadsA

Get list of files downloaded by the browser on a page.

Returns downloaded file info including suggested filenames and local paths. After clicking a download link, call this to retrieve the downloaded file path.

Args: page_id: Target page ID.

Inputs: page_id (required). Returns: object

browser_dragA

Drag one element to another by their [@eN] ref IDs from browser_snapshot.

Humanized by default: picks non-center points, follows a curved uneven mouse path, and uses randomized timing. If that fails, fallback=True retries with Playwright's native drag_to for HTML5 drag-and-drop compatibility. Returns an updated snapshot.

Args: page_id: Target page ID. source_ref: Ref ID of the element to drag. target_ref: Ref ID of the drop target. humanize: Use human-like mouse movement instead of direct drag_to. duration_ms: Approximate humanized drag duration, clamped to 250-5000 ms. steps: Number of mouse movement points, clamped to 8-80. fallback: Retry with Playwright drag_to if humanized drag fails.

Inputs: page_id (required), source_ref (required), target_ref (required), humanize, +3 more. Returns: object

browser_evaluateB

Execute JavaScript in the page context and return the result.

Args: page_id: Target page ID. expression: JavaScript expression to evaluate.

Inputs: page_id (required), expression (required). Returns: object

browser_forwardB

Navigate forward in browser history. Returns an updated snapshot.

Args: page_id: Target page ID.

Inputs: page_id (required). Returns: object

browser_get_cookiesC

Get all cookies from the page's browser context.

Args: page_id: Target page ID.

Inputs: page_id (required). Returns: object

browser_hoverB

Hover over an element by ref ID. Returns an updated snapshot.

Args: page_id: Target page ID. ref: Ref ID from snapshot.

Inputs: page_id (required), ref (required). Returns: object

browser_launchA

Launch a stealth CloakBrowser instance. All anti-detection is ON by default.

CloakBrowser is a source-patched Chromium passing Cloudflare Turnstile, reCAPTCHA v3 (0.9 score), FingerprintJS, BrowserScan, and 30+ detectors.

Args: headless: Run headless. Some aggressive sites need headed mode (False). proxy: Proxy URL (e.g. 'http://user:pass@proxy:8080'). Residential recommended. humanize: Human-like mouse/keyboard/scroll (default: True). human_preset: 'default' or 'careful' (slower, more deliberate). stealth_args: Apply stealth fingerprint args (default: True). timezone: IANA timezone (e.g. 'America/New_York'). locale: BCP 47 locale (e.g. 'en-US'). geoip: Auto-detect timezone/locale from proxy IP. fingerprint_seed: Fixed seed for consistent identity across sessions. user_data_dir: Persistent profile path (cookies/localStorage survive restarts). viewport_width: Viewport width in pixels (default: 1920 headless; 1280 headed fallback, or auto-detected). viewport_height: Viewport height in pixels (default: 947 headless; 800 headed fallback, or auto-detected). color_scheme: 'light', 'dark', or 'no-preference'. user_agent: Custom user agent override. extra_args: Additional Chromium CLI flags.

Inputs: headless, proxy, humanize, human_preset, +11 more. Returns: object

browser_list_pagesA

List all open pages with their IDs and URLs.

Inputs: no named parameters. Returns: object

browser_navigateA

Navigate to a URL. Auto-waits for the page to settle (network idle + DOM stable).

Handles Cloudflare challenge pages with extra wait time. Returns an updated snapshot of the loaded page.

Args: page_id: Target page ID. url: URL to navigate to. timeout: Navigation timeout in milliseconds.

Inputs: page_id (required), url (required), timeout. Returns: object

browser_network_continueA

Remove a network interception rule.

Args: page_id: Target page ID. url_pattern: Same pattern used in browser_network_intercept.

Inputs: page_id (required), url_pattern (required). Returns: object

browser_network_interceptA

Intercept network requests — block, mock, or passthrough.

Args: page_id: Target page ID. url_pattern: Glob pattern (e.g. '/api/', '**/*.png'). action: 'block', 'mock', or 'continue'. mock_body: Response body for 'mock' action. mock_status: HTTP status for 'mock' action. mock_content_type: Content-Type for 'mock' action.

Inputs: page_id (required), url_pattern (required), action, mock_body, +2 more. Returns: object

browser_new_pageA

Open a new browser page/tab. Optionally navigate to a URL.

Args: url: URL to navigate to after creating the page.

Inputs: url. Returns: object

browser_pdfB

Save the current page as a PDF file.

Args: page_id: Target page ID. format: Page format — 'A4', 'Letter', 'Legal'. print_background: Include background graphics.

Inputs: page_id (required), format, print_background. Returns: object

browser_press_keyA

Press a keyboard key (Enter, Tab, Escape, ArrowDown, etc.).

Returns an updated snapshot.

Args: page_id: Target page ID. key: Key name (DOM KeyboardEvent key).

Inputs: page_id (required), key (required). Returns: object

browser_read_pageA

Get the page content as clean, readable markdown.

Best for reading articles, docs, search results, or any content-heavy page. Strips navigation, ads, footers — returns just the main content. Much more token-efficient than raw HTML (60-80% savings).

Args: page_id: Target page ID. max_length: Max characters to return (default: 50000).

Inputs: page_id (required), max_length. Returns: object

browser_screenshotA

Take an annotated screenshot with element indices overlaid.

Each numbered element maps to [@eN] refs from browser_snapshot. Use when you need VISUAL context — images, charts, CAPTCHAs, or layout. For most interactions, prefer browser_snapshot() instead.

Returns: file path to saved PNG, element count.

Args: page_id: Target page ID. full_page: Capture entire scrollable page (default: viewport only).

Inputs: page_id (required), full_page. Returns: object

browser_scrollA

Scroll the page. Returns an updated snapshot.

Args: page_id: Target page ID. direction: 'up' or 'down'. amount: Pixels to scroll.

Inputs: page_id (required), direction, amount. Returns: object

browser_selectA

Select a dropdown option by ref ID. Provide one of: value, label, or index.

Returns an updated snapshot.

Args: page_id: Target page ID. ref: Ref ID of the element. value: Option value attribute to select. label: Option visible text to select. index: Option index (0-based) to select.

Inputs: page_id (required), ref (required), value, label, +1 more. Returns: object

browser_set_cookiesB

Set cookies in the page's browser context.

Args: page_id: Target page ID. cookies: List of cookie dicts with name, value, domain, path.

Inputs: page_id (required), cookies (required). Returns: object

browser_snapshotA

Capture the page's accessibility tree — the PRIMARY way to understand pages.

Returns interactive elements with [@eN] ref IDs for use with browser_click, browser_type, browser_select, browser_drag, etc. Call this BEFORE interacting with a page.

full=False (default): interactive elements only — compact and fast. full=True: includes surrounding text content for reading context.

This is FASTER, CHEAPER, and MORE RELIABLE than screenshots. Always prefer this over browser_screenshot for deciding what to click.

Args: page_id: Target page ID from browser_launch or browser_new_page. full: Include text content alongside interactive elements. max_length: Max characters to return (default: 12000).

Inputs: page_id (required), full, max_length. Returns: object

browser_typeA

Type text into an input by its [@eN] ref ID from browser_snapshot.

Clears the field first by default. Set submit=True to press Enter after. Returns an updated snapshot.

Args: page_id: Target page ID. ref: Ref ID from snapshot (e.g. '@e3' or 'e3'). text: Text to type. clear: Clear field before typing (default: True). submit: Press Enter after typing (default: False).

Inputs: page_id (required), ref (required), text (required), clear, +1 more. Returns: object

browser_waitA

Wait for the page to settle (no DOM mutations + network idle).

Use after actions that trigger dynamic content loading. Returns whether the page settled and how many DOM mutations occurred.

Args: page_id: Target page ID. timeout_ms: Max wait time in milliseconds (default: 5000).

Inputs: page_id (required), timeout_ms. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 28 tools

    Disambiguation5/5

    Each tool has a distinct purpose, covering specific browser actions like clicking, typing, scrolling, navigating, and extracting data. There is no overlap; even similar-sounding tools like browser_snapshot, browser_screenshot, and browser_read_page serve clearly different needs.

    Naming Consistency5/5

    All tools follow a consistent `browser_verb` pattern in snake_case, such as browser_launch, browser_click, browser_new_page. This predictable naming makes it easy for an agent to infer functionality.

    Tool Count4/5

    With 28 tools, the count is higher than the typical 3-15 range for a well-scoped server. However, the complex domain of browser automation justifies this many operations, and each tool serves a unique and necessary function.

    Completeness5/5

    The tool set covers the full lifecycle: launch, page management, navigation, interaction, data extraction, network control, cookies, and PDF generation. Only minor features like page refresh or file upload are missing, but the core workflows are fully supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers