Built on nodriver (direct CDP, no WebDriver leak) + curl_cffi (TLS fingerprint spoofing) + FastMCP.

One-line install with uvx:

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

Proven on Real Sites

🎯 click_turnstile → Cloudflare Turnstile Bypass

One-liner bypass on supported widget shapes. click_turnstile() → checkbox switches from "Verify you are human" ☐ to "Success!" ✅.

✅ Works on: 2captcha.com/demo/cloudflare-turnstile, dash.cloudflare.com login, nopecha.com/captcha/turnstile (via template-match fallback since v0.1.7), any page embedding the standard CF Turnstile widget with [data-sitekey] / .cf-turnstile / challenges.cloudflare.com iframe.

❌ Does NOT work on: Cloudflare managed-mode interstitials — the "Just a moment..." full-page challenge (e.g. nopecha.com/demo/cloudflare). CF scores the click as non-human and resets the Ray ID. For those pages use solve_captcha with a CAPSOLVER_KEY, or storage_state_load with a pre-warmed session.

🧪 bot.sannysoft.com → All Fingerprint Tests Pass

navigator.webdriver missing, WebDriver Advanced passed, Chrome present, Plugins detected correctly, PHANTOM_* probes all ok, WebGL shows real Apple M1 Pro GPU — nodriver's CDP-direct approach leaves zero automation traces.

🤖 areyouheadless → Headless Chrome Detection

Antoine Vastel's public headless-detection test says "You are not Chrome headless" — even though we run Chrome controlled programmatically.

🔍 browserscan.net/bot-detection → All Categories Normal

14 signals checked (WebDriver, WebDriver Advance, Selenium, NightmareJS, PhantomJS, Awesomium, Cef, CefSharp, Coaches, FMiner, Born, Phantomas, Rhino, Webdriverio, Headless Chrome, CDP, Dev Tool, Native Navigator) — every one returns "Normal".

🔐 TLS Fingerprint Proof

http_request(impersonate="chrome") vs vanilla Python httpx — tls.browserleaks.com:

Vanilla httpx:       JA3: 37f7d09ced1a845dc48872abc1a29d7b   UA: python-httpx/0.28.1    ❌ BOT
Chrome impersonate:  JA3: f830262a93191fd695c65531282d5657   UA: Chrome/146.0.0.0         ✅ real Chrome
Firefox impersonate: JA3: 6f7889b9fb1a62a9577e685c1fcfa919   UA: Firefox/147.0            ✅ real Firefox
Safari impersonate:  JA3: ecdf4f49dd59effc439639da29186671   UA: Safari/605.1.15          ✅ real Safari

Each impersonation produces authentic browser JA3/JA4 — Cloudflare, DataDome, and Akamai cannot distinguish our HTTP requests from real browsers.

🏆 reCAPTCHA v2 Benchmark (5 consecutive runs)

Fresh profile + mouse drift warmup + an OpenAI-compatible vision model:

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, 476⭐):

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:

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

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 -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 for detailed per-client setup + troubleshooting. Per-client snippets below:

claude mcp add stealth-chrome --scope user -- uvx mcp-stealth-chrome@latest

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

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "servers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "context_servers": {
    "stealth-chrome": {
      "command": {
        "path": "uvx",
        "args": ["mcp-stealth-chrome@latest"]
      }
    }
  }
}

🔑 BYOK (Bring Your Own Key) — Optional

mcp-stealth-chrome is fully functional without any API key — 167 of 172 tools work out of the box, including click_turnstile (Cloudflare Turnstile bypass), TLS-perfect HTTP, tracked request polling/cancellation, scoped snapshots, native image artifacts, multi-instance, DevTools-level perf/coverage/emulation, the full LLM-optimized kit (describe_page / smart_fill / workflow_run), the web-research kit (web_search / scrape_markdown / deep_research / social_research — no search-API key needed), and all scraping tools.

API keys are optional — only needed for 5 vision/solver tools:

• solve_recaptcha_ai, vision_locate, vision_describe, vision_ocr, vision_check | Tool | Purpose | Required key | Cost | |------|---------|--------------|------| | solve_recaptcha_ai | reCAPTCHA v2 image challenges via AI vision | Any vision-capable LLM (OpenAI-compat / Claude / Ollama) | ~$0.005-0.03 per solve | | vision_locate | Find DOM element by natural-language description ("the red Create button at bottom right") | Same vision provider as solve_recaptcha_ai | ~$0.001-0.01 per call | | solve_captcha | Turnstile, reCAPTCHA v2, reCAPTCHA v3, hCaptcha via paid solver | CapSolver API | ~$0.80-1.00 per 1000 |

Everything else (click_turnstile, verify_cf, storage_state, http_request, detect_anti_bot, clone_chrome_profile, etc.) works 100% without any key.

When BYOK Matters

• solve_recaptcha_ai → auto-solve reCAPTCHA v2 image challenges ("select all images with cars") via vision LLM. Best for: low-volume automation where you want self-hosted / BYO-key.
• solve_captcha → solve via CapSolver's dedicated captcha-solving service. Best for: production reliability, high success rate (95%+), handles multiple types (Turnstile + reCAPTCHA v2 + v3 + hCaptcha + more).

You can use either one or both depending on your budget and reliability needs. Add to the MCP env block.

⚠️ Model Must Be Multimodal (Vision-Capable)

solve_recaptcha_ai sends a screenshot + text prompt to the model — text-only models will fail silently.

✅ Vision-capable (supported):

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4-vision-preview, gpt-5.x
• Anthropic: claude-opus-4-7, claude-sonnet-4-*
• Local Ollama: llava, llava-llama3, bakllava, llama3.2-vision
• Groq: llama-3.2-90b-vision-preview
• Custom: any model documented as "multimodal" / "vision"

❌ Text-only (NOT supported):

• gpt-3.5-turbo, llama3 (non-vision variant), claude-3-haiku (limited)

Config Options

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
        "ANTHROPIC_MODEL":   "claude-opus-4-7"
      }
    }
  }
}

"env": {
  "OPENAI_API_KEY": "sk-proj-xxxxx",
  "OPENAI_MODEL":   "gpt-4o"
}

"env": {
  "OPENAI_BASE_URL": "https://your-provider.example.com/v1",
  "OPENAI_API_KEY":  "your-api-key",
  "OPENAI_MODEL":    "model-name-that-supports-vision"
}

"env": {
  "OPENAI_BASE_URL": "https://api.groq.com/openai/v1",
  "OPENAI_API_KEY":  "gsk_xxxxx",
  "OPENAI_MODEL":    "llama-3.2-90b-vision-preview"
}

ollama pull llava

"env": {
  "OPENAI_BASE_URL": "http://localhost:11434/v1",
  "OPENAI_API_KEY":  "ollama",
  "OPENAI_MODEL":    "llava:latest"
}

"env": {
  "CAPSOLVER_KEY": "CAP-xxxxxxxxxxxxx"
}

Provider Resolution Priority

1. Explicit args to solve_recaptcha_ai(provider=, base_url=, api_key=, model=)
2. OPENAI_API_KEY + OPENAI_BASE_URL + OPENAI_MODEL — standard (OpenAI SDK convention)
3. AI_VISION_API_KEY + AI_VISION_BASE_URL + AI_VISION_MODEL — deprecated (removed in v0.2.0)
4. ANTHROPIC_API_KEY + ANTHROPIC_MODEL — Claude

Legacy AI_VISION_* env still work but emit DeprecationWarning. Migrate to OPENAI_* standard for future compatibility.

Requirements

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

Honest reporting (v0.9.0)

Tools that report a rosier state than reality are the worst failure mode for an agent: the caller has no way to notice, so a wrong "success" spreads into wrong conclusions. These no longer lie:

New diagnostics: assert_clickable (would a click reach this? what's in the way? — without clicking) and wait_for_change (click-then-wait in one call, with an honest timeout). screenshot(region_selector="css") measures the crop box for you, removing the CSS-px-vs-device-px guesswork.

Reliability and review primitives

Clicks are real input. click, click_text and click_role dispatch trusted mouse events (isTrusted=true) after a hit test, scroll the target into view when needed, and refuse by name when something covers it. A JS click happens only with click(js_fallback=True), and the result says so.

browser_snapshot() writes nothing to the page: it runs in an isolated world and refs live on the server, mapped to CDP node ids. It reaches into iframes, cross-origin ones included, and open shadow roots, marking those elements frame=fN or shadow, and their refs work like any other. include_frames=False limits it to the main frame. Closed shadow roots cannot be measured. A frame that could not be read is listed as not measured.

Long-running pages no longer require manual sleep loops. evaluate(timeout_ms=600000, survive_navigation=True, tab=1) raises the per-call ceiling explicitly, while wait_for_function(expression, timeout_ms, poll_ms, tab) polls a side-effect-free predicate without changing focus. Navigation reports requested/final URLs, redirect chain, HTTP status, and ready state; expect_url and expect_status turn redirects into explicit failures.

browser_snapshot() defaults to interactive_compact with max_elements, container_selector, viewport_only, role, name_contains, and measured omission counts. screenshot(output_mode="artifact|inline_image|path|base64", tab=...) keeps base64 opt-in. screenshot_element(exact_bounds=True) captures an element, and inspect_image reports native dimensions, MIME, byte size, checksum, and a managed artifact.

Slow HTTP calls return a request ID for http_request_status polling or http_request_cancel; connection, read, and unknown outcomes remain distinct. Same-tab long operations are rejected while the target is busy instead of racing CDP.

⭐⭐⭐ Self-Sufficient Web Research (new) — replaces firecrawl/tavily for most tasks

Browserless-first (curl_cffi), escalates to the stealth browser only when a page is anti-bot blocked. Runs fully headless/API-mode and is ~10–12× lighter than driving Chrome for normal pages (verified: HTTP path 10–12× faster than headless render on example.com / Wikipedia).

⭐⭐⭐ Dual-Mode HTTP (unique)

⭐⭐ Precision Mouse Kit (unique)

⭐⭐ AI Vision Solver (unique)

| Tool | Purpose | | solve_recaptcha_ai | Vision LLM picks matching tiles — solve image challenges (auto-clicks anchor checkbox in v0.2.10+) | | vision_locate | NL → element coordinates; this tool locates only and does not caption | | vision_describe | Describe a viewport, page, or selector screenshot with a vision model | | vision_ocr | Extract visible text from a viewport, page, or selector screenshot | | vision_check | Validate criteria into {pass, findings}; malformed model output is reported as unknown |

⭐⭐⭐ AI-Agent Action Kit (LLM-optimized, new in v0.3.0)

Designed for LLM-driven workflows — token-efficient page summaries, label-fuzzy form filling, verification primitives, resumable orchestration.

⭐⭐ Network + Auth Bridge (new in v0.4.0)

Network capture with response bodies, plus a bridge from browser session into TLS-perfect HTTP for authenticated API debugging.

⭐⭐ Request Interception — see a request before the server does

⭐ Stealth Toolkit

Local Human Handoff

Multi-Instance

Choosing a profile mode

What privacy=True changes: the browser starts from an empty profile, that profile is deleted on close, and a proxy written as a pool (a|b) picks one member. What it does not change: the identity. User agent, Chrome version, operating system, language and timezone remain the real browser's and machine's in every mode, because a made-up identity on a real engine contradicts itself. To use a logged-in account, leave privacy off.

Any identity field can be overridden per launch, in any mode: fingerprint={"user_agent": ..., "accept_language": ..., "platform": ..., "timezone": ...}. Fields you leave out stay real. Client hints (navigator.userAgentData) and a missing navigator.platform are derived from the user agent so they agree with it, and navigator.languages comes from accept_language with the ;q= weights removed.

One server, many agents (HTTP mode)

mcp-stealth-chrome --http                # http://127.0.0.1:8765/mcp

stdio stays the default and behaves as before: each client starts its own server. With --http, one server serves every client, and each connection (Mcp-Session-Id) gets its own instances, tabs and logs. An instance belonging to another session is refused by name until that session calls instance_release.

This server can act as whoever is logged in to its browsers, so access is locked down by default:

• A bearer token is always required. It comes from MCP_STEALTH_TOKEN, or from ~/.mcp-stealth/http-token, created on first run with mode 600. It is never printed. Send it as Authorization: Bearer <token>.
• Loopback only by default. Any other --host is refused without --allow-remote, and the token then travels unencrypted unless a TLS proxy fronts it. Behind a proxy or on a wildcard address, name what clients use with --allowed-host.
• Host and Origin checks stay on, so a web page cannot reach the server through DNS rebinding.

Limits to know about:

• A Chrome profile can only be open once, so a second session's default browser uses its own profile (~/.mcp-stealth/profiles/session-N) without the first session's logins. Use instance_release, or clone the profile with clone_chrome_profile.
• Subagents sharing one MCP connection are one session to the server, and still share state.
• Each session runs its own Chrome, so this mode saves server processes, not browser memory.
• A client that ends its session leaves its browsers to be claimed or closed by the idle timeout.
• A few capture features remain one per server: request interception (a second session gets a clear refusal) and performance tracing.

Disk and memory

⭐⭐ DevTools Suite — perf, coverage, emulation (new in v0.2.0)

⚡ Performance optimizations

Standard Browser Automation (lifecycle/navigation/DOM/interaction/scraping)

Example Workflows

One-liner Cloudflare Turnstile bypass (embed widget)

browser_launch(url="https://site-with-turnstile.com")
mouse_drift(duration_seconds=2)                    # natural behavior
click_turnstile()                                  # works on embedded widgets
# Login button now enabled, fill form, submit

Works on pages that embed the CF Turnstile widget (.cf-turnstile, [data-sitekey], or a challenges.cloudflare.com iframe). For managed-mode interstitials ("Just a moment..." full-page challenges), this tool cannot bypass — use solve_captcha or storage_state_load instead.

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": [...]}

Social-media market/competitor research (who sells + how loud)

browser_launch()
social_research(
  topic="AI carousel generator",
  platforms="reddit,threads,facebook",
  cookie_files="threads.json,fb.json",   # auto-(re)imports sessions — crash-resilient
)
# One call → per platform: Google site: dork (clean, non-personalized) + native
# in-platform search (engagement/likes/views). Reddit needs no login; Threads/FB/X
# use your imported session. Read the posts to judge sentiment / rank sellers.

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

Deprecated (still work but emit DeprecationWarning — migrate to OpenAI standards above): AI_VISION_BASE_URL, AI_VISION_API_KEY, AI_VISION_MODEL, AI_VISION_PROVIDER

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:

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

git clone https://github.com/RobithYusuf/mcp-stealth-chrome
cd mcp-stealth-chrome
uv sync
uv run mcp-stealth-chrome       # run stdio server locally
uv run mcp-stealth-chrome --http   # or one HTTP server for many clients

Testing:

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

Credits

• nodriver by ultrafunkamsterdam — undetected Chrome via CDP
• curl_cffi by lexiforest — TLS browser impersonation
• FastMCP — Python MCP SDK
• Camoufox by daijro — sister Firefox stealth (via mcp-camoufox)
• CapSolver — CAPTCHA solving API
• vibheksoni/stealth-browser-mcp — complementary MCP for UI cloning & network hooks

License

MIT — see LICENSE.