# CloakMCP [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/overtimepog/CloakMCP  
**GitHub Stars:** 12  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cloakmcp

## Description
Stealth browser MCP server — anti-detection Chromium with snapshot-first agent interface

## Tools
Capabilities this server exposes over MCP:

- **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
- **cloak_network_intercept** — Block/mock/passthrough requests
- **cloak_network_continue** — Remove interception rule
- **cloak_get_cookies** — Get all cookies
- **cloak_set_cookies** — Set cookies
- **cloak_pdf** — Save page as PDF
- **cloak_console** — Get browser console output

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "cloakmcp": {
    "command": "uvx",
    "args": ["cloakbrowsermcp"]
  }
}
```

## Documentation & README

# CloakBrowser MCP

<!-- mcp-name: io.github.overtimepog/CloakMCP -->

**Stealth browser automation for AI agents** — a [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
pip install cloakbrowsermcp
```

### Use with Claude Desktop

Add to your `claude_desktop_config.json`:

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

### Use with VS Code / Cursor

Add to `.vscode/mcp.json`:

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

### Use with Hermes Agent

Add to `~/.hermes/config.yaml`:

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

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)

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

```python
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

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

```bash
git clone https://github.com/overtimepog/CloakMCP
cd CloakMCP
pip install -e ".[dev]"
pytest
```

## License

Apache-2.0