{
  "markdown": "# CloakBrowser MCP\n\n<!-- mcp-name: io.github.overtimepog/CloakMCP -->\n\n**Stealth browser automation for AI agents** — a [Model Context Protocol](https://modelcontextprotocol.io) server combining CloakBrowser's anti-detection with Playwright MCP-inspired architecture.\n\nCloakBrowser is a source-level patched Chromium that passes Cloudflare Turnstile, reCAPTCHA v3 (0.9 score), FingerprintJS, BrowserScan, and 30+ bot detection services.\n\n## Why CloakBrowser MCP?\n\n| Feature | Playwright MCP | CloakBrowser MCP |\n|---------|---------------|-----------------|\n| Anti-detection | ❌ None | ✅ Source-patched Chromium |\n| Cloudflare bypass | ❌ | ✅ |\n| reCAPTCHA v3 | ❌ | ✅ 0.9 score |\n| Snapshot-first | ✅ | ✅ |\n| Markdown extraction | ❌ | ✅ Readability-style |\n| Annotated screenshots | ❌ | ✅ browser-use style |\n| Smart page settling | Basic | ✅ MutationObserver + networkidle |\n| Auto-retry clicks | ❌ | ✅ |\n| Humanized input | ❌ | ✅ Mouse curves, keyboard timing |\n| Capability gating | ✅ --caps | ✅ --caps |\n\n## Quick Start\n\n### Install\n\n```bash\npip install cloakbrowsermcp\n```\n\n### Use with Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cloakbrowser\": {\n      \"command\": \"cloakbrowsermcp\"\n    }\n  }\n}\n```\n\n### Use with VS Code / Cursor\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"cloakbrowser\": {\n      \"command\": \"cloakbrowsermcp\",\n      \"args\": [\"--caps\", \"all\"]\n    }\n  }\n}\n```\n\n### Use with Hermes Agent\n\nAdd to `~/.hermes/config.yaml`:\n\n```yaml\nmcp_servers:\n  cloakbrowser:\n    command: cloakbrowsermcp\n    args: [\"--caps\", \"all\"]\n    timeout: 120\n```\n\n## How It Works\n\n### Snapshot-First Architecture\n\nCloakBrowser MCP uses **accessibility tree snapshots** as the primary way for AI models to understand web pages — not screenshots, not raw HTML.\n\n```\n1. cloak_launch()           → Start stealth browser\n2. cloak_navigate(pid, url) → Go to page (auto-waits for settle)\n3. cloak_snapshot(pid)      → Get interactive elements with [@eN] refs\n4. cloak_click(pid, '@e5')  → Click element by ref\n5. cloak_type(pid, '@e3', 'hello')  → Type into input\n6. cloak_read_page(pid)     → Get content as clean markdown\n7. cloak_close()            → Done\n```\n\nEach interactive element gets a `[@eN]` ref ID. All interaction tools use these refs — no CSS selectors needed.\n\n### Three Ways to See a Page\n\n1. **`cloak_snapshot()`** — Accessibility tree with `[@eN]` refs. Fast, cheap, reliable. **Use this.**\n2. **`cloak_read_page()`** — Clean markdown extraction. For reading content, not interacting.\n3. **`cloak_screenshot()`** — Annotated screenshot with element indices. For visual context (images, charts, CAPTCHAs).\n\n### Stealth by Default\n\nAll anti-detection features are **ON by default**:\n- Source-patched Chromium binary (not Playwright patches — actual Chromium source modifications)\n- Human-like mouse curves, keyboard timing, and scroll patterns (`humanize=True`)\n- Stealth fingerprint arguments (consistent canvas, WebGL, audio fingerprints)\n- Proxy support with GeoIP-based timezone/locale detection\n\n## Tools\n\n### Core Tools (20 — always available)\n\n| Tool | Description |\n|------|-------------|\n| `cloak_launch` | Start stealth browser (all anti-detection ON) |\n| `cloak_close` | Close browser and release resources |\n| `cloak_snapshot` | **PRIMARY** — accessibility tree with `[@eN]` refs |\n| `cloak_click` | Click element by ref (auto-retry) |\n| `cloak_type` | Type into input by ref (with submit option) |\n| `cloak_select` | Select dropdown option by ref |\n| `cloak_hover` | Hover over element by ref |\n| `cloak_check` | Check/uncheck checkbox by ref |\n| `cloak_read_page` | Page content as clean markdown |\n| `cloak_screenshot` | Annotated screenshot with element indices |\n| `cloak_navigate` | Go to URL (auto-waits for settle) |\n| `cloak_back` | Navigate back in history |\n| `cloak_forward` | Navigate forward in history |\n| `cloak_press_key` | Press keyboard key |\n| `cloak_scroll` | Scroll page up/down |\n| `cloak_wait` | Wait for page to settle |\n| `cloak_evaluate` | Execute JavaScript in page |\n| `cloak_new_page` | Open new page/tab |\n| `cloak_list_pages` | List all open pages |\n| `cloak_close_page` | Close a specific page |\n\n### Capability-Gated Tools (enabled via `--caps`)\n\nEnable with `cloakbrowsermcp --caps network,cookies,pdf,console` or `--caps all`.\n\n| Tool | Capability | Description |\n|------|-----------|-------------|\n| `cloak_network_intercept` | network | Block/mock/passthrough requests |\n| `cloak_network_continue` | network | Remove interception rule |\n| `cloak_get_cookies` | cookies | Get all cookies |\n| `cloak_set_cookies` | cookies | Set cookies |\n| `cloak_pdf` | pdf | Save page as PDF |\n| `cloak_console` | console | Get browser console output |\n\n## Configuration\n\n### CLI Options\n\n```\ncloakbrowsermcp [--caps CAPS] [--transport {stdio,sse}] [--port PORT]\n```\n\n- `--caps`: Comma-separated capabilities: `network`, `cookies`, `pdf`, `console`, `all`\n- `--transport`: MCP transport — `stdio` (default) or `sse`\n- `--port`: Port for SSE transport (default: 8931)\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CLOAKBROWSER_LOG_LEVEL` | `INFO` | Log level |\n| `CLOAKBROWSER_LOG_FILE` | `~/.cloakbrowser/logs/server.log` | Log file path |\n| `CLOAKBROWSER_LOG_STDERR` | `false` | Also log to stderr |\n\n### Launch Options\n\n```python\ncloak_launch(\n    headless=True,        # False for headed mode (some sites require it)\n    proxy=\"http://...\",   # Residential proxy recommended\n    humanize=True,        # Human-like input (ON by default)\n    stealth_args=True,    # Stealth fingerprints (ON by default)\n    timezone=\"America/New_York\",\n    locale=\"en-US\",\n    geoip=False,          # Auto-detect from proxy IP\n    fingerprint_seed=\"my-identity\",  # Consistent fingerprint across sessions\n    user_data_dir=\"/path\",  # Persistent profile\n)\n```\n\n## Architecture\n\n```\ncloakbrowsermcp/\n├── server.py      # FastMCP server, tool registration, error handling\n├── session.py     # Browser lifecycle, page management, ref storage\n├── snapshot.py    # Accessibility tree JS, ref resolution\n├── markdown.py    # Readability-style HTML-to-markdown extraction\n├── vision.py      # Annotated screenshots with element indices\n├── waiting.py     # Smart wait, page settle, retry logic\n├── stealth.py     # Stealth config inspection\n├── network.py     # Network intercept, cookies (capability-gated)\n├── __init__.py\n└── __main__.py\n```\n\n### Design Principles\n\n1. **Snapshot-first** — Tool descriptions steer models to use `cloak_snapshot()` as the primary page understanding tool\n2. **Ref-based only** — No CSS selector tools. All interaction via `[@eN]` refs from snapshots\n3. **Stealth by default** — Anti-detection, humanization, and stealth args all ON without configuration\n4. **Auto-snapshot after actions** — Click, type, navigate all return an updated snapshot\n5. **Smart waiting** — Auto-wait on navigation (networkidle + MutationObserver settle), auto-retry on failed clicks\n6. **Capability gating** — Advanced tools (network, cookies, PDF) off by default to keep tool count low\n7. **Clean content extraction** — Markdown for reading, snapshot for interaction, annotated screenshots for vision\n\n## Development\n\n```bash\ngit clone https://github.com/overtimepog/CloakMCP\ncd CloakMCP\npip install -e \".[dev]\"\npytest\n```\n\n## License\n\nApache-2.0\n",
  "bytes": 7393,
  "sha": "fb5a037e033f641ba1fa03a4a5394b05371d7653cfe19391c95fd17e6ee1fe58",
  "repo_slug": "overtimepog/cloakmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_overtimepog_cloakmcp_5e44c892/readme"
}