Metadata-Version: 2.3
Name: mcp-stealth-chrome
Version: 0.1.0
Summary: Stealth Chrome MCP server — nodriver + Chromium + 80+ tools with Cloudflare/Turnstile bypass, CapSolver, storage-state reuse
Keywords: mcp,model-context-protocol,nodriver,stealth,anti-detection,cloudflare-bypass,turnstile,browser-automation,chromium,chrome,claude,captcha
Author: RobithYusuf
Author-email: RobithYusuf <robithdev@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Dist: mcp>=1.2.0
Requires-Dist: nodriver>=0.40
Requires-Dist: pydantic>=2.5
Requires-Dist: httpx>=0.27
Requires-Dist: opencv-python>=4.8
Requires-Dist: curl-cffi>=0.7
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/RobithYusuf/mcp-stealth-chrome
Project-URL: Repository, https://github.com/RobithYusuf/mcp-stealth-chrome
Project-URL: Issues, https://github.com/RobithYusuf/mcp-stealth-chrome/issues
Description-Content-Type: text/markdown

<div align="center">

# MCP Stealth Chrome

**94 tools** for AI agents that bypass Cloudflare, Turnstile, reCAPTCHA, and modern anti-bot systems.

[![PyPI version](https://img.shields.io/pypi/v/mcp-stealth-chrome.svg)](https://pypi.org/project/mcp-stealth-chrome/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org)

Browser stealth when you need eyes. TLS-perfect HTTP when you need speed.

</div>

---

Built on [nodriver](https://github.com/ultrafunkamsterdam/nodriver) (direct CDP, no WebDriver leak) + [curl_cffi](https://github.com/lexiforest/curl_cffi) (TLS fingerprint spoofing) + [FastMCP](https://github.com/modelcontextprotocol/python-sdk).

One-line install with `uvx`:

```bash
claude mcp add stealth-chrome -- uvx mcp-stealth-chrome@latest
```

## Proven on Real Sites

| Site | Challenge | Result |
|------|-----------|--------|
| `bot.sannysoft.com` | All fingerprint tests | ✅ 100% pass |
| `dash.cloudflare.com/login` | Turnstile visible | ✅ Passed via `click_turnstile()` |
| `tls.browserleaks.com` | TLS JA3/JA4 fingerprint | ✅ Real Chrome/Firefox/Safari |
| `httpbin.org` | Multi-instance isolation | ✅ Two browsers parallel |
| `google.com/recaptcha/api2/demo` | **reCAPTCHA v2 image challenge** | ✅ **5/5 = 100%** via `solve_recaptcha_ai()` |

### 🏆 reCAPTCHA v2 Benchmark (5 consecutive runs)

Fresh profile + mouse drift warmup + gpt-5.4 via patungin.id (OpenAI-compat):

```
Run 1: ✅ 2169ch token, tiles=[3,4,7],         146s
Run 2: ✅ 2126ch token, tiles=[0,2,4,7],        80s
Run 3: ✅ 2169ch token, tiles=[1,2,4,8],       143s
Run 4: ✅ 2148ch token, tiles=[1,4,5,6,8,9],  126s
Run 5: ✅ 2169ch token, tiles=[0,3,4],          69s

Success rate: 5/5 = 100%
Avg solve:   113s
Token range: 2126–2169 chars (all Google-accepted)
```

**First OSS MCP with proven 100% reCAPTCHA v2 bypass via BYO-API-key** — works with
Claude, gpt-4o, gpt-5.x, Gemini, Groq, local Ollama, any OpenAI-compatible vision model.

Method: neutral prompt language bypasses LLM safety filter + auto-refresh challenge
when vision returns empty + dynamic 3x3/4x4 grid detection + humanized mouse behavior.

## Key Differentiators

Compared to the leading Python stealth MCP ([vibheksoni/stealth-browser-mcp](https://github.com/vibheksoni/stealth-browser-mcp), 476⭐):

| Feature | mcp-stealth-chrome | vibheksoni |
|---------|:-------------------:|:-----------:|
| Tools | **94** | 90 |
| `click_turnstile` one-liner | ✅ **Proven bypass** | ❌ |
| Dual-mode HTTP (curl_cffi TLS) | ✅ **Unique** | ❌ |
| AI Vision reCAPTCHA solver (Claude) | ✅ **Unique** | ❌ |
| Precision Mouse Kit (11 tools) | ✅ **Unique** | ❌ |
| Multi-instance + idle reaper | ✅ | ✅ |
| Install | `uvx` zero-setup | `git clone + pip` |
| Sister Firefox package | ✅ [mcp-camoufox](https://github.com/RobithYusuf/mcp-camoufox) | ❌ |
| Network interception hooks | ⚠️ basic | ✅ **AI-generated Python hooks** |
| Pixel-perfect element cloning | ⚠️ basic | ✅ **300+ CSS + events** |

**Different niches**: we focus on anti-bot bypass, they focus on UI reverse-engineering. Both MCPs work great together.

## Quick Install (3 commands per OS)

**macOS:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh        # install uv
brew install --cask google-chrome                       # install Chrome (skip if already installed)
claude mcp add stealth-chrome --scope user -- uvx mcp-stealth-chrome@latest
```

**Linux (Ubuntu/Debian):**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
sudo apt install -y google-chrome-stable                # or chromium-browser
claude mcp add stealth-chrome --scope user -- uvx mcp-stealth-chrome@latest
```

**Windows (PowerShell):**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
winget install Google.Chrome
claude mcp add stealth-chrome --scope user -- uvx mcp-stealth-chrome@latest
```

No Chrome? Server gives a friendly error with install instructions before failing.

See [INSTALL.md](INSTALL.md) for detailed per-client setup (Claude Code / Desktop / Cursor). TL;DR below:

<details>
<summary><b>Claude Code CLI</b></summary>

```bash
# Global (available in all projects):
claude mcp add stealth-chrome --scope user -- uvx mcp-stealth-chrome@latest

# Project only:
claude mcp add stealth-chrome -- uvx mcp-stealth-chrome@latest
```
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}
```
</details>

### Optional: API Keys for CAPTCHA Solvers

`solve_recaptcha_ai` works with **Claude OR any OpenAI-compatible vision API** (gpt-4o, gpt-5.x, Groq, Ollama local, patungin.id, Together.ai, etc). Pick one:

**Anthropic Claude:**
```json
"env": {
  "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
  "CAPSOLVER_KEY": "CAP-xxxxx"
}
```

**OpenAI-compatible (any provider with `/v1/chat/completions`):**
```json
"env": {
  "AI_VISION_BASE_URL": "https://ai.patungin.id/v1",
  "AI_VISION_API_KEY":  "your-key-here",
  "AI_VISION_MODEL":    "gpt-5.4"
}
```

Or vanilla OpenAI (inherits default base URL):
```json
"env": {
  "OPENAI_API_KEY": "sk-xxxxx",
  "AI_VISION_MODEL": "gpt-4o"
}
```

Provider priority: explicit args to tool > `AI_VISION_*` env > `OPENAI_API_KEY` > `ANTHROPIC_API_KEY`.

## Requirements

- Python 3.11+
- `uv` installed: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Chrome or Chromium browser (auto-detected by nodriver)

## Tool Categories (94)

### ⭐⭐⭐ Dual-Mode HTTP (unique)
| Tool | Purpose |
|------|---------|
| `http_request` | TLS-perfect HTTP via curl_cffi (chrome/firefox/safari impersonation) |
| `http_session_cookies` | Inspect which browser cookies match a URL |
| `session_warmup` | Natural browsing pattern (homepage/referer/scroll) before target |
| `detect_anti_bot` | Identify CF/DataDome/PerimeterX/Kasada/Imperva on current page |

### ⭐⭐ Precision Mouse Kit (unique)
| Tool | Purpose |
|------|---------|
| `click_turnstile` | One-liner CF Turnstile bypass (proven) |
| `click_element_offset` | Click at % position inside element (not center) |
| `click_at_corner` | Click top-left/right/bottom-left/right of element |
| `find_by_image` | OpenCV template match → coordinates |
| `click_at_image` | Find image + click its center |
| `mouse_drift` | Random Bezier wandering (pass behavioral ML) |
| `mouse_record` / `mouse_replay` | Capture real human mouse patterns, replay |

### ⭐⭐ AI Vision Solver (unique)
| Tool | Purpose |
|------|---------|
| `solve_recaptcha_ai` | Claude vision picks matching tiles — solve image challenges |

### ⭐ Stealth Toolkit
| Tool | Purpose |
|------|---------|
| `storage_state_save` / `storage_state_load` | Portable session export — bypass Turnstile via reuse |
| `solve_captcha` | CapSolver API — Turnstile/reCAPTCHA/hCaptcha |
| `verify_cf` | Cloudflare checkbox via OpenCV template match |
| `fingerprint_rotate` | UA/lang/platform/timezone via CDP |
| `humanize_click` / `humanize_type` | Bezier+Gaussian for single actions |

### Multi-Instance
| Tool | Purpose |
|------|---------|
| `spawn_browser` | New named instance (parallel profiles) |
| `list_instances` / `switch_instance` | Manage multiple browsers |
| `close_instance` / `close_all_instances` | Clean shutdown |

### Standard Browser Automation (lifecycle/navigation/DOM/interaction/scraping)
| Count | Examples |
|-------|----------|
| Lifecycle: 2 | browser_launch, browser_close |
| Navigation: 4 | navigate, go_back, go_forward, reload |
| DOM/Content: 6 | browser_snapshot, screenshot, get_text, get_html, get_url, save_pdf |
| Interaction: 9 | click, click_text, click_role, hover, fill, select_option, check, uncheck, upload_file |
| Keyboard: 2 | type_text, press_key |
| Mouse: 3 | mouse_click_xy, mouse_move, drag_and_drop |
| Wait: 4 | wait_for, wait_for_navigation, wait_for_url, wait_for_response |
| Tabs: 4 | tab_list, tab_new, tab_select, tab_close |
| Cookies/Storage: 8 | cookie_list/set/delete, localstorage_get/set/clear, sessionstorage_get/set |
| JavaScript: 2 | evaluate, inject_init_script |
| Inspection: 4 | inspect_element, get_attribute, query_selector_all, get_links |
| Frames: 2 | list_frames, frame_evaluate |
| Batch: 3 | batch_actions, fill_form, navigate_and_snapshot |
| Viewport/Scroll/Dialog/A11y: 5 | get/set_viewport_size, scroll, dialog_handle, accessibility_snapshot |
| Console/Network: 4 | console_start/get, network_start/get |
| Debug: 3 | server_status, get_page_errors, export_har |
| Scraping: 4 | detect_content_pattern, extract_structured, extract_table, scrape_page |

## Example Workflows

### One-liner Cloudflare Turnstile bypass

```
browser_launch(url="https://site-with-turnstile.com")
mouse_drift(duration_seconds=2)                    # natural behavior
click_turnstile()                                  # ✅ proven bypass
# Login button now enabled, fill form, submit
```

### Bypass Turnstile via saved session (most reliable)

```
# Once — manual:
browser_launch(url="https://target.com/login", headless=false)
# [user logs in manually in browser window]
storage_state_save(filename="target-session.json")
browser_close()

# Every time after — automated:
browser_launch(
  url="https://target.com/dashboard",
  headless=true,                                   # can go headless
  storage_state_path="~/.mcp-stealth/storage-states/target-session.json"
)
# Turnstile never triggers — session is valid
```

### Solve reCAPTCHA v2 image challenge via Claude

```
browser_launch(url="https://site-with-recaptcha.com")
click_element_offset(ref="recaptcha-checkbox-ref", x_percent=8)
# Image challenge appears
solve_recaptcha_ai(max_rounds=3)                   # uses ANTHROPIC_API_KEY
# Token injected, form ready to submit
```

### Multi-account scraping in parallel

```
browser_launch(url="https://site.com", headless=true)   # main instance
spawn_browser("account_2", url="https://site.com", headless=true)
spawn_browser("account_3", url="https://site.com", headless=true)

list_instances()                                   # see all 3 running
switch_instance("account_2")
# All subsequent tool calls target account_2
click(ref="login-btn")
...
switch_instance("main")                            # back to main
```

### Browser login + fast API scraping

```
# Login with browser (renders JS, solves challenges)
browser_launch(url="https://api-site.com/login")
click_turnstile()
fill(ref="email-ref", value="you@example.com")
fill(ref="password-ref", value="...")
click(ref="submit-ref")

# Scrape API 10x faster with TLS-perfect HTTP
http_request(
  url="https://api-site.com/v1/data",
  impersonate="chrome",
  use_browser_cookies=true                         # reuse login session
)
```

### Auto-detect anti-bot + recommended strategy

```
browser_launch(url="https://unknown-site.com")
detect_anti_bot()
# Returns: {"detected": ["Cloudflare", "reCAPTCHA"],
#           "recommended_tools": [...]}
```

## Architecture

```
uvx mcp-stealth-chrome → Python 3.11 → FastMCP → nodriver → Chrome/Chromium
                                                  ↓
                                          curl_cffi (TLS)
```

Data locations:
- Profile (main): `~/.mcp-stealth/profile/`
- Profiles (multi-instance): `~/.mcp-stealth/profiles/<instance_id>/`
- Screenshots: `~/.mcp-stealth/screenshots/`
- Exports (PDF, HAR): `~/.mcp-stealth/exports/`
- Storage states: `~/.mcp-stealth/storage-states/`

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `BROWSER_IDLE_TIMEOUT` | `600` | Auto-close browsers after idle seconds (0 = never) |
| `BROWSER_IDLE_REAPER_INTERVAL` | `60` | How often reaper checks idle state |
| `CAPSOLVER_KEY` | — | Enable `solve_captcha` tool |
| `ANTHROPIC_API_KEY` | — | `solve_recaptcha_ai` via Claude |
| `AI_VISION_BASE_URL` | — | `solve_recaptcha_ai` via OpenAI-compat API |
| `AI_VISION_API_KEY` | — | API key for OpenAI-compat provider |
| `AI_VISION_MODEL` | `claude-opus-4-7` or `gpt-4o` | Vision model name |
| `AI_VISION_PROVIDER` | auto-detect | Force `anthropic` or `openai` |
| `OPENAI_API_KEY` | — | Shortcut for OpenAI (default base URL) |

## Stealth Details

Underlying tech stack:
- **nodriver** — Python CDP client with no WebDriver/Runtime.Enable leaks
- **curl_cffi** — libcurl with CFFI, matches Chrome/Firefox/Safari TLS handshake exactly (JA3/JA4 authenticity)
- **OpenCV** — template matching for visual CAPTCHA checkbox detection

Bypass layer vs detection:

| Detection | Bypass |
|-----------|--------|
| `navigator.webdriver` | nodriver doesn't set it |
| `Runtime.Enable` CDP leak | nodriver avoids it |
| Automation flags | No `--enable-automation` |
| Headless fingerprint | `headless=false` recommended for hard targets |
| TLS/JA3/JA4 | `http_request(impersonate='chrome')` |
| Turnstile checkbox | `click_turnstile()` |
| reCAPTCHA v2 image | `solve_recaptcha_ai()` or `solve_captcha()` |
| Behavioral ML | `mouse_drift`, `mouse_record/replay`, `humanize_click/type` |

**Honest limits** — these are HARDEST OSS bypass targets and require commercial services for production:
- DataDome (real-time behavioral ML across 50+ signals)
- Kasada (proprietary JS, rotates daily)
- PerimeterX/HUMAN (ML-based request scoring)
- ChatGPT managed Turnstile (checks React internal state)

For these, `storage_state_save/load` (manual-login-once, reuse) is the most reliable OSS approach.

## Sister Package

[mcp-camoufox](https://github.com/RobithYusuf/mcp-camoufox) — Firefox stealth with same API. Use when you need:
- Hardest anti-bot bypass (Camoufox C++ level patches = stealth score 6% CreepJS)
- Firefox-specific rendering
- Node.js ecosystem

Both packages share tool names, snapshot format, ref system — switch seamlessly.

## Development

```bash
git clone https://github.com/RobithYusuf/mcp-stealth-chrome
cd mcp-stealth-chrome
uv sync
uv run mcp-stealth-chrome       # run stdio server locally
```

Testing:
```bash
uv run python /tmp/smoke-test.py      # full smoke test (see /tmp/ examples)
```

## Credits

- [nodriver](https://github.com/ultrafunkamsterdam/nodriver) by ultrafunkamsterdam — undetected Chrome via CDP
- [curl_cffi](https://github.com/lexiforest/curl_cffi) by lexiforest — TLS browser impersonation
- [FastMCP](https://github.com/modelcontextprotocol/python-sdk) — Python MCP SDK
- [Camoufox](https://github.com/daijro/camoufox) by daijro — sister Firefox stealth (via [mcp-camoufox](https://github.com/RobithYusuf/mcp-camoufox))
- [CapSolver](https://capsolver.com) — CAPTCHA solving API
- [vibheksoni/stealth-browser-mcp](https://github.com/vibheksoni/stealth-browser-mcp) — complementary MCP for UI cloning & network hooks

## License

MIT — see [LICENSE](LICENSE).
