io.github.overtimepog/CloakMCP
Stealth browser MCP server β anti-detection Chromium with snapshot-first agent interface
Ask AI about io.github.overtimepog/CloakMCP
Powered by Claude Β· Grounded in docs
I know everything about io.github.overtimepog/CloakMCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 |
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
2. cloak_navigate(pid, url) β Go to page (auto-waits for settle)
3. cloak_snapshot(pid) β Get interactive elements with [@eN] refs
4. cloak_click(pid, '@e5') β Click element by ref
5. cloak_type(pid, '@e3', 'hello') β Type into input
6. cloak_read_page(pid) β Get content as clean markdown
7. 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
cloak_snapshot()β Accessibility tree with[@eN]refs. Fast, cheap, reliable. Use this.cloak_read_page()β Clean markdown extraction. For reading content, not interacting.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)
| Tool | Description |
|---|---|
cloak_launch | Start stealth browser (all anti-detection ON) |
cloak_close | Close browser and release resources |
cloak_snapshot | PRIMARY β accessibility tree with [@eN] refs |
cloak_click | Click element by ref (auto-retry) |
cloak_type | Type into input by ref (with submit option) |
cloak_select | Select dropdown option by ref |
cloak_hover | Hover over element by ref |
cloak_check | Check/uncheck checkbox by ref |
cloak_read_page | Page content as clean markdown |
cloak_screenshot | Annotated screenshot with element indices |
cloak_navigate | Go to URL (auto-waits for settle) |
cloak_back | Navigate back in history |
cloak_forward | Navigate forward in history |
cloak_press_key | Press keyboard key |
cloak_scroll | Scroll page up/down |
cloak_wait | Wait for page to settle |
cloak_evaluate | Execute JavaScript in page |
cloak_new_page | Open new page/tab |
cloak_list_pages | List all open pages |
cloak_close_page | Close a specific page |
Capability-Gated Tools (enabled via --caps)
Enable with cloakbrowsermcp --caps network,cookies,pdf,console or --caps all.
| Tool | Capability | Description |
|---|---|---|
cloak_network_intercept | network | Block/mock/passthrough requests |
cloak_network_continue | network | Remove interception rule |
cloak_get_cookies | cookies | Get all cookies |
cloak_set_cookies | cookies | Set cookies |
cloak_pdf | Save page as PDF | |
cloak_console | console | Get browser console output |
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) orsse--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
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
)
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
- Snapshot-first β Tool descriptions steer models to use
cloak_snapshot()as the primary page understanding tool - Ref-based only β No CSS selector tools. All interaction via
[@eN]refs from snapshots - Stealth by default β Anti-detection, humanization, and stealth args all ON without configuration
- Auto-snapshot after actions β Click, type, navigate all return an updated snapshot
- Smart waiting β Auto-wait on navigation (networkidle + MutationObserver settle), auto-retry on failed clicks
- Capability gating β Advanced tools (network, cookies, PDF) off by default to keep tool count low
- 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
