# 🚀 MCP Stealth Browser (`mcp-stealth-browser`)

[![Smithery Badge](https://smithery.ai/badge/@AntonLi-PM/mcp-stealth-browser)](https://smithery.ai/server/@AntonLi-PM/mcp-stealth-browser)
[![GitHub Release](https://img.shields.io/github/v/release/AntonLi-PM/mcp-stealth-browser?color=blue&style=for-the-badge)](https://github.com/AntonLi-PM/mcp-stealth-browser/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![MCP Standard](https://img.shields.io/badge/Protocol-MCP%20v1.0-purple?style=for-the-badge)](https://modelcontextprotocol.io/)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg?style=for-the-badge)](https://www.python.org/)
[![Cloudflare Bypass](https://img.shields.io/badge/Cloudflare-Turnstile%20Bypass-green?style=for-the-badge)](https://github.com/AntonLi-PM/mcp-stealth-browser)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](https://github.com/AntonLi-PM/mcp-stealth-browser/pulls)

> 💡 **Facing IP Bans, Zero-View Shadowbans, or Captcha Loops?**
> Need custom dedicated residential IP pools or enterprise setup assistance?
> 🎁 **[Claim 1GB Free Residential Proxy Trial](https://ropond.com/)** | 💬 **Telegram Support:** [@ip38888](https://t.me/ip38888) | ✉️ **Email:** [anton.li.pm@gmail.com](mailto:anton.li.pm@gmail.com) | 📊 **[Live Benchmark](https://antonli-pm.github.io/anti-bot-bypass-benchmark/)**

> ⭐ **Love this project? Please consider starring it on GitHub!** It helps keep the open-source residential IP anti-bot benchmark updated.
> 
> 🔥 **Check Out Our High-Performance AI & Agentic Suite**:
> - 🤖 **[llm-web-grounding-proxy](https://github.com/AntonLi-PM/llm-web-grounding-proxy)**: Universal OpenAI reverse proxy injecting real-time search & citations.
> - 🧠 **[agentic-deep-researcher](https://github.com/AntonLi-PM/agentic-deep-researcher)**: Autonomous AI deep researcher with recursive multi-hop scraping.
> - 🌐 **[mcp-stealth-browser](https://github.com/AntonLi-PM/mcp-stealth-browser)**: FastMCP 2.x stealth browser server for Claude Desktop, Cursor & Windsurf.
> - 🛡️ **[antidetect-proxy-router](https://github.com/AntonLi-PM/antidetect-proxy-router)**: Profile-isolated residential proxy router for Playwright & Camoufox.



> **The High-Performance Stealth Web Browsing & Search MCP Server for Claude Desktop, Cursor, Windsurf & Cline.**  
> Bypasses Cloudflare Turnstile, anti-bot shields, and JavaScript SPAs with dual-engine TLS/Playwright impersonation, dynamic residential proxy rotation, and token-optimized semantic Markdown extraction.

---

## 🏛️ Architecture Overview

```mermaid
flowchart LR
    A[LLM Agent<br/>Claude / Cursor / Cline] -->|JSON-RPC 2.0| B(MCP Stealth Server)
    B -->|Task Router| C{Engine Dispatcher}
    C -->|Tier 1: Fast Path <400ms| D[TLS Impersonator<br/>curl_cffi / JA3 / JA4]
    C -->|Tier 2: Challenge Escalation| E[Stealth Playwright<br/>CDP Hooks + Turnstile Solver]
    D --> F[Sticky Residential Proxy Router<br/>Ropond Proxy Cloud]
    E --> F
    F -->|Clean IP Lease| G((Target Website))
    G --> H[Token Optimizer Engine<br/>HTML to Semantic Markdown]
    H -->|80-95% Token Savings| A
```

---

## 📊 Feature Comparison Matrix

| Capability | `mcp-stealth-browser` | `@modelcontextprotocol/server-fetch` | `playwright-mcp` | `puppeteer-mcp` |
| :--- | :---: | :---: | :---: | :---: |
| **Cloudflare Turnstile Bypass** | ✅ **Native (<400ms / Dual-Engine)** | ❌ (Throws 403) | ⚠️ (Requires manual script) | ❌ (Blocked) |
| **DataDome / Akamai Evasion** | ✅ **JA3/JA4 TLS Fingerprint** | ❌ (No impersonation) | ❌ (Detectable CDP) | ❌ (Detectable) |
| **Multi-Engine Web Search** | ✅ **Built-in (Zero API Keys)** | ❌ (None) | ❌ (None) | ❌ (None) |
| **Context Token Optimization** | ✅ **80-95% Compression (Markdown)** | ⚠️ (Basic Markdownify) | ❌ (Raw DOM dump) | ❌ (Raw dump) |
| **Sticky Residential Proxy Pool** | ✅ **Auto-Rotation on 403/429** | ❌ (Static proxy only) | ❌ (None) | ❌ (None) |
| **Response Latency** | ⚡ **< 400ms** (TLS tier) | 1 - 3s | 5 - 12s | 5 - 15s |
| **1-Click Install** | 🚀 **Smithery (`npx`) / `uvx`** | `uvx` | `npx` | `npx` |

---

## ⚡ Why `mcp-stealth-browser`?

Standard web fetch and browser MCP servers (`@modelcontextprotocol/server-fetch`, `playwright-mcp`) fail on **70%+ of modern websites**:
- ❌ **Cloudflare & Anti-Bot Blocking**: Hit with `403 Forbidden` or `Just a moment...` CAPTCHA loops.
- ❌ **Token Window Explosion**: Dump raw HTML with bloated scripts, SVGs, and cookie modals, wasting 100k+ tokens.
- ❌ **IP Rate-Limits**: Repeated queries from data center IPs get permanently blocked.
- ❌ **No Native Multi-Engine Web Search**: Requires expensive Bing/Google API keys to search the web.

### 🌟 What `mcp-stealth-browser` solves:
- ✅ **Dual-Engine Cascade**: Fast TLS/JA4 browser impersonation (`<400ms`) with auto-escalation to headless Playwright when Cloudflare Turnstile or DataDome is detected.
- ✅ **Built-in Real-Time Web Search**: `stealth_search` crawls Google & DuckDuckGo simultaneously with zero API keys.
- ✅ **Token-Optimized Markdown**: Strips navigation, headers, footers, and scripts, compressing content by **80-95%** while preserving tables, headings, and code snippets.
- ✅ **Sticky Residential Proxy Pool**: Dynamic residential proxy rotation with 10-30 minute sticky IP sessions and automatic block recovery.
- ✅ **Universal 1-Click Integration**: Drop-in configuration for **Claude Desktop**, **Cursor IDE**, **Windsurf**, and **Cline**.

---

## 🛠️ MCP Tools Exposed

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `stealth_fetch` | `url`, `bypass_challenge=True`, `session_id` | Fetches any URL bypassing Cloudflare Turnstile, returns clean semantic Markdown with token estimation. |
| `stealth_search` | `query`, `num_results=5`, `session_id` | Multi-engine real-time web search (DuckDuckGo + Google) returning clean ranked citations with zero API keys. |
| `proxy_status` | *none* | Returns proxy pool health, active sticky sessions, and residential IP provider status. |
| `rotate_proxy` | `session_id` | Forces an immediate IP rotation for a specific sticky session. |

---

## 📦 Quick Start & Configuration

### 0. 1-Click Install via Smithery (Recommended)

To automatically install for **Claude Desktop**, run:
```bash
npx -y @smithery/cli install @AntonLi-PM/mcp-stealth-browser --client claude
```

To install for **Cursor**, run:
```bash
npx -y @smithery/cli install @AntonLi-PM/mcp-stealth-browser --client cursor
```

---

### 1. Manual Install via pip or uv
```bash
pip install git+https://github.com/AntonLi-PM/mcp-stealth-browser.git
# Optional: Install Playwright for heavy Turnstile challenge solving
playwright install chromium
```

### 2. Configure in Claude Desktop
Add to your `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "stealth-browser": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AntonLi-PM/mcp-stealth-browser.git", "mcp-stealth-browser"],
      "env": {
        "ROTA_PROXY_URL": "http://user:pass@proxy.ropond.com:8080"
      }
    }
  }
}
```

### 3. Configure in Cursor IDE
Add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "stealth-browser": {
      "command": "python",
      "args": ["-m", "mcp_stealth_browser"],
      "env": {
        "ROTA_PROXY_URL": "http://user:pass@proxy.ropond.com:8080"
      }
    }
  }
}
```

---

## 🌐 Residential Proxy Setup (High-Volume Scraping)

For high-concurrency scraping without IP blocks, `mcp-stealth-browser` natively integrates with dynamic residential proxies:

1. Obtain a residential proxy gateway (claim a **1GB Free Trial** at [Ropond Proxy Cloud](https://ropond.com/)).
2. Set the environment variable:
```bash
export ROTA_PROXY_URL="http://customer-xyz:pass@gw.ropond.com:8080"
```
3. `mcp-stealth-browser` will automatically create sticky sessions per agent conversation and rotate automatically if a 403 or 429 block is encountered.

---

## 🧪 Testing Locally

You can test the search and fetch capabilities directly from CLI:

```bash
# Test multi-engine search
python -m mcp_stealth_browser.cli --test-search "DeepSeek R1 reasoning architecture"

# Test stealth fetch on a webpage
python -m mcp_stealth_browser.cli --test-fetch "https://news.ycombinator.com"

# Check proxy pool health
python -m mcp_stealth_browser.cli --status
```

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/AntonLi-PM/mcp-stealth-browser/issues).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🧭 Related Open-Source Tools in Our Suite

Explore our complete production-grade anti-bot & matrix marketing open-source ecosystem:

| Category | Repository | Description |
| :--- | :--- | :--- |
| **Global Matrix** | [`omni-social-marketing-cloud`](https://github.com/AntonLi-PM/omni-social-marketing-cloud) | 12-platform multi-account cloud control with 1:1 sticky residential IP mesh |
| **Telegram Growth** | [`telegram-cloud-controller`](https://github.com/AntonLi-PM/telegram-cloud-controller) | Multi-account Telegram fleet automation, warmup engine & lead harvester |
| **WhatsApp Marketing**| [`whatsapp-marketing-cloud`](https://github.com/AntonLi-PM/whatsapp-marketing-cloud) | Multi-account WhatsApp Web cloud sender with session residential routing |
| **TikTok Automation** | [`tiktok-uploader-stealth`](https://github.com/AntonLi-PM/tiktok-uploader-stealth) | Anti-detect TikTok video batch uploader with isolated proxy sessions |
| **E-Commerce Scraper**| [`ecommerce-intelligence-scraper`](https://github.com/AntonLi-PM/ecommerce-intelligence-scraper) | Competitor price monitor & review scraper for Amazon, Shopee & Shopify |
| **AI Deep Research**  | [`agentic-deep-researcher`](https://github.com/AntonLi-PM/agentic-deep-researcher) | Autonomous Deep Research engine utilizing heavy multi-hop residential scraping |
| **AI Realtime Search**| [`deepseek-r1-websearch`](https://github.com/AntonLi-PM/deepseek-r1-websearch) | Real-time web search API for DeepSeek-R1, Ollama & Open-WebUI |
| **MCP Browser Tool**  | [`mcp-stealth-browser`](https://github.com/AntonLi-PM/mcp-stealth-browser) | FastMCP 2.x stealth browsing server for Claude Desktop, Cursor & Windsurf |
| **Anti-Bot Gateway**  | [`searxng-proxy-shield`](https://github.com/AntonLi-PM/searxng-proxy-shield) | Rotating residential proxy shield for SearXNG, Perplexica & Open-WebUI |
| **Profile Router**    | [`antidetect-proxy-router`](https://github.com/AntonLi-PM/antidetect-proxy-router) | Profile-isolated residential proxy router for AdsPower, BitBrowser & Playwright |
| **Turnstile Bypass**  | [`cloudflare-bypass-residential-scraper`](https://github.com/AntonLi-PM/cloudflare-bypass-residential-scraper) | Turnstile & DataDome bypass scraper with residential session harvesting |
| **Live Benchmark**    | [`anti-bot-bypass-benchmark`](https://github.com/AntonLi-PM/anti-bot-bypass-benchmark) | Empirical anti-bot benchmark comparing datacenter vs residential proxy yields |