TerrysPOV/stealth-browser-mcp

Supercharge any MCP-compatible AI agent with undetectable, real-browser automation. No CAPTCHAs. No blocks. Just results.

🌐 Live Deployment

✅ Production Ready: https://stealth-browser-mcp.onrender.com
🔍 Health Check: /mcp endpoint
📡 Transport: Server-Sent Events (SSE)
🚀 Ready for: OpenAI Playground, Claude, and other MCP clients

⚡ 30-second setup • 🛡️ Undetectable by design • 🏆 98.7% success rate on protected sites • 🕵️ Full network debugging via AI chat

Give your AI agent real browser superpowers: access Cloudflare sites, extract any UI, and intercept network traffic — from inside your chat.

🎥 See It In Action

🎯 Watch: Stealth Browser MCP bypassing Cloudflare, cloning UI elements, and intercepting network traffic — all through simple AI chat commands

🔗 Quick Links

• ▶️ Quickstart
• 🏆 - Impossible automations made possible
• 🥊 - Why we dominate the competition
• 🔥 - Copy & paste prompts that blow minds
• 🧰 90 Tools - Complete arsenal of browser automation
• 🎥 - See it bypass what others can't
• 🤝 Contributing & 💬 Discord

Quickstart (60 seconds)

✅ Recommended Setup (Creator's Tested Method)

# 1. Clone the repository
git clone https://github.com/vibheksoni/stealth-browser-mcp.git
cd stealth-browser-mcp

# 2. Create virtual environment
python -m venv venv

# 3. Activate virtual environment
# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Add to Claude Code using CLI

Windows (Full Installation):

claude mcp add-json stealth-browser-mcp "{\"type\":\"stdio\",\"command\":\"C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe\",\"args\":[\"C:\\path\\to\\stealth-browser-mcp\\src\\server.py\"]}"

Windows (Minimal - Core Tools Only):

claude mcp add-json stealth-browser-mcp "{\"type\":\"stdio\",\"command\":\"C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe\",\"args\":[\"C:\\path\\to\\stealth-browser-mcp\\src\\server.py\",\"--minimal\"]}"

Mac/Linux (Full Installation):

claude mcp add-json stealth-browser-mcp '{
  "type": "stdio",
  "command": "/path/to/stealth-browser-mcp/venv/bin/python",
  "args": [
    "/path/to/stealth-browser-mcp/src/server.py"
  ]
}'

Mac/Linux (Custom - Disable Advanced Features):

claude mcp add-json stealth-browser-mcp '{
  "type": "stdio",
  "command": "/path/to/stealth-browser-mcp/venv/bin/python",
  "args": [
    "/path/to/stealth-browser-mcp/src/server.py",
    "--disable-cdp-functions",
    "--disable-dynamic-hooks"
  ]
}'

💡 Replace /path/to/stealth-browser-mcp/ with your actual project path

⚠️ Alternative: FastMCP CLI (Untested by Creator)

These methods should theoretically work but have not been tested by the creator. Use at your own risk.

# Install FastMCP
pip install fastmcp

# Auto-install (untested)
fastmcp install claude-desktop src/server.py --with-requirements requirements.txt
# OR
fastmcp install claude-code src/server.py --with-requirements requirements.txt  
# OR
fastmcp install cursor src/server.py --with-requirements requirements.txt

Alternative: Manual Configuration (If Claude CLI not available)

If you don't have Claude Code CLI, manually add to your MCP client configuration:

Claude Desktop - Windows (%APPDATA%\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "stealth-browser-full": {
      "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
      "env": {}
    },
    "stealth-browser-minimal": {
      "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py", "--minimal"],
      "env": {}
    }
  }
}

Claude Desktop - Mac/Linux (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "stealth-browser-full": {
      "command": "/path/to/stealth-browser-mcp/venv/bin/python",
      "args": ["/path/to/stealth-browser-mcp/src/server.py"],
      "env": {}
    },
    "stealth-browser-custom": {
      "command": "/path/to/stealth-browser-mcp/venv/bin/python",
      "args": [
        "/path/to/stealth-browser-mcp/src/server.py",
        "--disable-cdp-functions",
        "--disable-dynamic-hooks"
      ],
      "env": {}
    }
  }
}

🎛️ NEW: Customize Your Installation

Stealth Browser MCP now supports modular tool loading! Disable sections you don't need:

# Minimal installation (only core browser + element interaction)
python src/server.py --minimal

# Custom installation - disable specific sections
python src/server.py --disable-cdp-functions --disable-dynamic-hooks

# List all 11 available tool sections
python src/server.py --list-sections

Available sections:

• browser-management (11 tools) - Core browser operations
• element-interaction (11 tools) - Page interaction and manipulation
• element-extraction (9 tools) - Element cloning and extraction
• file-extraction (9 tools) - File-based extraction tools
• network-debugging (5 tools) - Network monitoring and interception
• cdp-functions (13 tools) - Chrome DevTools Protocol execution
• progressive-cloning (10 tools) - Advanced element cloning
• cookies-storage (3 tools) - Cookie and storage management
• tabs (5 tools) - Tab management
• debugging (6 tools) - Debug and system tools (includes new environment validator)
• dynamic-hooks (10 tools) - AI-powered network hooks

💡 Pro Tip: Use --minimal for lightweight deployments or --disable-* flags to exclude functionality you don't need!

Quick Test

Restart your MCP client and ask your agent:

"Use stealth-browser to navigate to https://example.com and extract the pricing table."

🚨 Common Installation Issues

❌ ERROR: Could not find a version that satisfies the requirement [package]

• Solution: Make sure your virtual environment is activated: venv\Scripts\activate (Windows) or source venv/bin/activate (Mac/Linux)
• Alternative: Try upgrading pip first: pip install --upgrade pip

❌ Module not found errors when running server

• Solution: Ensure virtual environment is activated before running
• Check paths: Make sure the Claude CLI command uses the correct venv path

❌ Chrome/Browser issues

• Solution: The server will automatically download Chrome when first run
• No manual Chrome installation needed

❌ "Failed to connect to browser" / Root user issues

• Solution: ✅ FIXED in v0.2.4! Auto-detects root/administrator and adds --no-sandbox automatically
• Manual fix: Add "args": ["--no-sandbox", "--disable-setuid-sandbox"] to spawn_browser calls
• Diagnostic tool: Use validate_browser_environment_tool() to check your environment

❌ "Input validation error" with args parameter

• Solution: ✅ FIXED in v0.2.4! Now accepts both JSON arrays and JSON strings:
  • "args": ["--no-sandbox"] (preferred)
  • "args": "[\"--no-sandbox\"]" (also works)

❌ Container/Docker issues

• Solution: ✅ FIXED in v0.2.4! Auto-detects containers and adds required arguments
• Manual fix: Add "args": ["--no-sandbox", "--disable-dev-shm-usage", "--disable-gpu"]

❌ "claude mcp add-json" command not found

• Solution: Make sure you have Claude Code CLI installed
• Alternative: Use manual configuration method above

❌ Path errors in Windows

• Solution: Use double backslashes \\ in JSON strings for Windows paths
• Example: "C:\\\\Users\\\\name\\\\project\\\\venv\\\\Scripts\\\\python.exe"

✨ Why developers star this

• Works on protected sites that block traditional automation
• Pixel-accurate element cloning via Chrome DevTools Protocol
• Full network debugging through AI chat — see every request, response, header, and payload
• Your AI agent becomes a network detective — no more guessing what APIs are being called
• 🎛️ Modular architecture — disable unused sections, run minimal installs
• ⚡ Lightweight deployments — from 22 core tools to full 89-tool arsenal
• Clean MCP integration — no custom brokers or wrappers needed
• 90 focused tools organized into 11 logical sections

Built on nodriver + Chrome DevTools Protocol + FastMCP

🎯 NEW: Advanced Text Input

Latest Enhancement (v0.2.3): Revolutionary text input capabilities that solve common automation challenges:

⚡ Instant Text Pasting

# NEW: paste_text() - Lightning-fast text input via CDP
await paste_text(instance_id, "textarea", large_markdown_content, clear_first=True)

• 10x faster than character-by-character typing
• Uses Chrome DevTools Protocol insert_text for maximum compatibility
• Perfect for large content (README files, code blocks, forms)

📝 Smart Newline Handling

# ENHANCED: type_text() with newline parsing
await type_text(instance_id, "textarea", "Line 1\nLine 2\nLine 3", parse_newlines=True, delay_ms=10)

• parse_newlines=True: Converts \n to actual Enter key presses
• Essential for multi-line forms, chat apps, and text editors
• Maintains human-like typing with customizable speed

🔧 Why This Matters

• Form Automation: Handle complex multi-line inputs correctly
• Content Management: Paste large documents instantly without timeouts
• Chat Applications: Send multi-line messages with proper line breaks
• Code Input: Paste code snippets with preserved formatting
• Markdown Editors: Handle content with proper line separations

Real-world impact: What used to take 30+ seconds of character-by-character typing now happens instantly, with proper newline handling for complex forms.

🛡️ NEW: Cross-Platform Compatibility & Root Support

Latest Enhancement (v0.2.4): Automatic platform detection and privilege handling that eliminates common browser spawning issues:

⚙️ Smart Environment Detection

# NEW: Automatic privilege detection and sandbox handling
validate_browser_environment_tool()  # Diagnose your environment

• Root/Administrator Detection: Auto-adds --no-sandbox when running as root
• Container Detection: Detects Docker/Kubernetes and adds container-specific args
• Platform-Aware: Handles Windows, Linux, macOS differences automatically
• Chrome Discovery: Automatically finds Chrome/Chromium installation

🔧 Flexible Args Handling

// All these formats now work:
{"args": ["--disable-web-security"]}                    // JSON array
{"args": "[\"--disable-web-security\"]"}              // JSON string  
{"args": "--disable-web-security"}                     // Single string

• Multiple Format Support: Accepts JSON arrays, JSON strings, or single strings
• Smart Parsing: Tries JSON first, falls back gracefully
• Backward Compatible: Existing configurations continue to work

📊 Built-in Diagnostics

# NEW: Environment validation tool
validate_browser_environment_tool()
# Returns: platform info, Chrome path, issues, warnings, recommendations

• Pre-flight Checks: Validates environment before browser launch
• Issue Detection: Identifies common problems and provides solutions
• Platform Insights: Detailed system information for debugging

🎯 Why This Matters

• Root User Support: No more "Failed to connect to browser" on Linux servers
• Container Compatibility: Works in Docker, Kubernetes, and serverless environments
• Windows Administrator: Handles UAC and privilege escalation scenarios
• Error Prevention: Catches issues before they cause failures
• Better Debugging: Clear diagnostics for troubleshooting

Real-world impact: Browser spawning now works reliably across all environments - from local development to production containers to CI/CD pipelines.

🎛️ Modular Architecture

NEW in v0.2.2: Stealth Browser MCP now supports modular tool loading! Choose exactly what functionality you need:

⚙️ Installation Modes

📦 Tool Sections

# List all sections with tool counts
python src/server.py --list-sections

# Examples:
python src/server.py --minimal                    # Only browser + element interaction
python src/server.py --disable-cdp-functions      # Disable Chrome DevTools functions  
python src/server.py --disable-dynamic-hooks      # Disable AI network hooks
python src/server.py --disable-debugging          # Disable debug tools

Benefits:

• 🚀 Faster startup - Only load tools you need
• 💾 Smaller memory footprint - Reduce resource usage
• 🏗️ Cleaner interface - Less tool clutter in AI chat
• ⚙️ Environment-specific - Different configs for dev/prod

🆚 Stealth vs Playwright MCP

Sites users care about: LinkedIn • Instagram • Twitter/X • Amazon • Banking • Government portals • Cloudflare APIs • Nike SNKRS • Ticketmaster • Supreme

Toolbox

🎨 Featured Demo: Augment Code Hero Clone

🎯 Real Conversation: User asked Claude to clone the Augment Code hero section. Here's what happened:

User Prompt:

"hey spawn a browser and clone the hero of the site https://www.augmentcode.com/"

What Claude Did Automatically:

1. Spawned undetectable browser instance
2. Navigated to augmentcode.com
3. Identified hero section using DOM analysis
4. Extracted complete element with all styles, structure, and assets
5. Generated pixel-perfect HTML recreation with inline CSS
6. Enhanced it to be even better with animations and responsive design

Result:

✅ Perfect pixel-accurate recreation of the entire hero section
✅ Professional animations and hover effects
✅ Fully responsive design across all devices
✅ Complete functionality including navigation and CTA button
✅ All done through simple AI chat - no manual coding required

The entire process took under 2 minutes of AI conversation!

Key Features Demonstrated:

• 🎨 CDP-accurate element extraction - Gets every CSS property perfectly
• 🎬 Advanced UI recreation - Builds production-ready HTML/CSS
• 📱 Responsive enhancement - Adds mobile optimization automatically
• ✨ Animation enhancement - Improves the original with smooth transitions
• 🚀 One-command automation - Complex task executed via simple chat

💡 This showcases the real power of Stealth Browser MCP - turning complex web cloning tasks into simple AI conversations.

🧪 Real‑world examples

• Market research: extract pricing/features from 5 competitors and output a comparison
• UI/UX cloning: recreate a pricing section with exact fonts, styles, and interactions
• Inventory monitoring: watch a product page and alert when in stock
• Reverse engineering: intercept requests, map endpoints, and understand data flow

You can drive all of the above from a single AI agent chat.

🛣️ Roadmap

See the live plan in . Contributions welcome.

Contributing

We love first‑time contributions. Read and open a PR.

If this project saves you time, consider starring the repo and sharing it with a friend.

💼 Need Website or App Development? Try DevHive Studios

DevHive Studios is a fair marketplace connecting businesses with skilled developers. Unlike other platforms, we put developers first while keeping costs affordable for clients.

🏆 Why DevHive?

• For Developers: Keep 60% of what clients pay (+ bonuses for on-time delivery)
• For Clients: Quality websites/apps starting at just $50
• For Everyone: Transparent pricing, fast delivery, expert team

🛠️ Services Available

Web development • Mobile apps • Bots & automation • E-commerce • UI/UX design • Security • Custom software • And more

Ready to start your project? Hit up DevHive Studios today:

• 🌐 devhivestudios.com
• 💬 Contact on Discord

DevHive Studios — Fair marketplace. Quality results.

☕ Support This Project

If this browser automation MCP saved you time or made you money, consider supporting the development:

• ☕ Buy me a coffee: buymeacoffee.com/vibheksoni
• ₿ Bitcoin: 3QaS5hq2416Gd3386M6c9g5Dgc5RgvP3o2
• Ł Litecoin: MM35KN1wUXREpwjj2RsmiKHM1ZWKDmeqDz
• ◎ Solana: 3LkBXDKLZXAgCRzAApa6dQG3ba7zRkUK82Bvmd9JWMdi

Every contribution helps maintain and improve this project! 🚀

📄 License

MIT — see .

If you want your AI agent to access ANY website, star this repo. It helps more than you think.

⭐ Star History