mcp-cloakbrowser 0.2.0

MCP server for CloakBrowser - stealth browser automation via Model Context Protocol

CloakBrowser MCP Server

English | 中文

Stealth browser automation via Model Context Protocol, powered by CloakBrowser.

A drop-in MCP server that wraps CloakBrowser's stealth Chromium with 57 source-level C++ fingerprint patches — not JS injection. Passes all 30/30 bot detection tests (reCAPTCHA v3 score: 0.9, Cloudflare Turnstile: PASS, FingerprintJS: PASS).

All tools use the cloak_ prefix to avoid conflicts with Hermes Agent's built-in browser_* tools.

Features

• 22 cloak tools — navigate, click, type, screenshot, console, evaluate JS, form filling, drag & drop, and more
• Stealth by default — navigator.webdriver = false, real Chrome TLS fingerprint, no CDP detection
• Human-like behavior — humanize=True enables Bézier mouse curves, per-character keyboard timing
• Proxy support — HTTP & SOCKS5 with GeoIP auto-detection
• Session persistence — save/load cookies and localStorage
• Compatible with any MCP client — Hermes Agent, Claude Desktop, Cursor, etc.
• No naming conflicts — cloak_* prefix won't collide with Hermes built-in browser_* tools

Quick Start

Install

pip install mcp-cloakbrowser

Run

# As a stdio MCP server
mcp-cloakbrowser

# Or directly
python -m cloakbrowser_mcp.server

Use with Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  cloakbrowser:
    command: "python"
    args: ["-m", "cloakbrowser_mcp.server"]
    timeout: 120

Restart Hermes Agent. Tools will be registered as mcp_cloakbrowser_cloak_*.

Use with Claude Desktop

Add to claude_desktop_config.json:

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

Available Tools

All tools use the cloak_ prefix (registered as mcp_cloakbrowser_cloak_* in Hermes):

Tool	Description
cloak_launch	Launch a stealth CloakBrowser instance
cloak_close	Close the browser and clean up
cloak_navigate	Navigate to a URL, return compact snapshot
cloak_snapshot	Get accessibility tree with ref IDs
cloak_click	Click element by ref (e.g. @e5)
cloak_type	Type text into input field by ref
cloak_press	Press keyboard key (Enter, Tab, Escape...)
cloak_scroll	Scroll page up/down
cloak_back	Navigate back in history
cloak_forward	Navigate forward in history
cloak_console	Get console logs or evaluate JS
cloak_get_images	List all images with URLs and alt text
cloak_screenshot	Take PNG screenshot
cloak_wait_for	Wait for element or text to appear
cloak_evaluate	Evaluate JavaScript expression
cloak_get_content	Get text/HTML of page or element
cloak_extract_links	Extract all links as JSON
cloak_fill_form	Fill multiple form fields at once
cloak_hover	Hover over element by ref
cloak_select_option	Select options in <select> elements
cloak_drag	Drag element to another element
cloak_save_storage_state	Save cookies/localStorage to file
cloak_load_storage_state	Load cookies/localStorage from file
cloak_info	Get current page URL, title, viewport

Tool Usage Examples

Navigate and Interact

# Launch browser
await call_tool("cloak_launch", {"headless": True, "humanize": True})

# Navigate to a page
await call_tool("cloak_navigate", {"url": "https://example.com"})

# Get snapshot to see interactive elements
snapshot = await call_tool("cloak_snapshot", {})
# Shows: [@e1] <a>Link text, [@e2] <input>[type: text]...

# Click a link
await call_tool("cloak_click", {"ref": "@e1"})

# Type into search box
await call_tool("cloak_type", {"ref": "@e2", "text": "hello world", "submit": True})

# Take screenshot
await call_tool("cloak_screenshot", {})

Fill a Login Form

await call_tool("cloak_fill_form", {
    "fields": [
        {"ref": "@e1", "value": "username"},
        {"ref": "@e2", "value": "password123"},
    ],
    "submit_ref": "@e3",
})

Advanced: Custom Fingerprint & Proxy

await call_tool("cloak_launch", {
    "headless": True,
    "humanize": True,
    "proxy": "socks5://user:pass@proxy:1080",
    "fingerprint_seed": "my-unique-seed-123",
    "geoip": True,
    "locale": "zh-CN",
})

Save/Restore Session

# Save session after login
await call_tool("cloak_save_storage_state", {"path": "session.json"})

# Later: restore session
await call_tool("cloak_load_storage_state", {"path": "session.json"})

Why cloak_* Prefix?

Hermes Agent has built-in browser_* tools (browser_navigate, browser_click, etc.) that use its own Playwright instance. Using the same names would cause conflicts. The cloak_ prefix makes it clear these tools use CloakBrowser's stealth Chromium, and allows you to use both in the same session:

• browser_navigate → Hermes built-in Playwright (fast, no stealth)
• cloak_navigate → CloakBrowser stealth Chromium (passes bot detection)

Architecture

MCP Client (Hermes/Claude/etc.)
    │ stdio (JSON-RPC)
    ▼
mcp-cloakbrowser server
    │
    ▼
CloakBrowser (Playwright-compatible API)
    │
    ▼
Stealth Chromium (57 C++ patches)

The server maintains a single browser instance (singleton pattern). All tools operate on the current page. The browser is auto-launched on first tool call if not explicitly launched.

Development

git clone https://github.com/MiwooMiwoo/cloakbrowser-mcp.git
cd cloakbrowser-mcp
pip install -e ".[dev]"

License

MIT