Stealth Browser MCP

🚀 The ONLY browser automation that bypasses Cloudflare, antibots, and social media blocks

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

⚡ 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
🏆 Hall of Fame - Impossible automations made possible
🥊 Stealth vs Others - Why we dominate the competition
🔥 Viral Examples - Copy & paste prompts that blow minds
🧰 90 Tools - Complete arsenal of browser automation
🎥 Live Demos - 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 detect Chrome, Chromium, or Microsoft Edge when first run
No manual browser installation needed - supports Chrome, Chromium, and Edge

❌ "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

🌐 Browser Support: Chrome • Chromium • Microsoft Edge (automatic detection)

🎯 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
Browser Discovery: Automatically finds Chrome, Chromium, or Microsoft Edge 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

Mode	Tools	Use Case
Full	90 tools	Complete browser automation & debugging
Minimal (`--minimal`)	22 tools	Core browser automation only
Custom	Your choice	Disable specific sections you don't need

📦 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

Feature	Stealth Browser MCP	Playwright MCP
Cloudflare/Queue-It	Consistently works	Commonly blocked
Banking/Gov portals	Works	Frequently blocked
Social sites	Full automation	Captchas/bans
UI cloning	CDP-accurate	Limited
Network debugging	AI agent sees all requests/responses	Basic
API reverse engineering	Full payload inspection via chat	Manual tools only
Dynamic Hook System	AI writes Python functions for real-time request processing	Not available
Modular Architecture	11 sections, 22-89 tools	Fixed ~20 tools
Tooling	90 (customizable)	~20

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

Toolbox

Browser Management

Tool	Description
`spawn_browser()`	Create undetectable browser instance
`navigate()`	Navigate to URLs
`close_instance()`	Clean shutdown of browser
`list_instances()`	Manage multiple sessions
`get_instance_state()`	Full browser state information
`go_back()`	Navigate back in history
`go_forward()`	Navigate forward in history
`reload_page()`	Reload current page
`hot_reload()`	Reload modules without restart
`reload_status()`	Check module reload status

Element Interaction

Tool	Description
`query_elements()`	Find elements by CSS/XPath
`click_element()`	Natural clicking
`type_text()`	Human-like typing with newline support
`paste_text()`	NEW! Instant text pasting via CDP
`scroll_page()`	Natural scrolling
`wait_for_element()`	Smart waiting
`execute_script()`	Run JavaScript
`select_option()`	Dropdown selection
`get_element_state()`	Element properties

Element Extraction (CDP‑accurate)

Tool	Description
`extract_complete_element_cdp()`	Complete CDP-based element clone
`clone_element_complete()`	Complete element cloning
`extract_complete_element_to_file()`	Save complete extraction to file
`extract_element_styles()`	300+ CSS properties via CDP
`extract_element_styles_cdp()`	Pure CDP styles extraction
`extract_element_structure()`	Full DOM tree
`extract_element_events()`	React/Vue/framework listeners
`extract_element_animations()`	CSS animations/transitions
`extract_element_assets()`	Images, fonts, videos
`extract_related_files()`	Related CSS/JS files

File-Based Extraction

Tool	Description
`extract_element_styles_to_file()`	Save styles to file
`extract_element_structure_to_file()`	Save structure to file
`extract_element_events_to_file()`	Save events to file
`extract_element_animations_to_file()`	Save animations to file
`extract_element_assets_to_file()`	Save assets to file
`clone_element_to_file()`	Save complete clone to file
`list_clone_files()`	List saved clone files
`cleanup_clone_files()`	Clean up old clone files

Network Debugging & Interception

🕵️ Turn your AI agent into a network detective! No more Postman, no more browser dev tools — just ask your agent what APIs are being called.

Basic Network Monitoring

Tool	Description
`list_network_requests()`	Ask AI: "What API calls happened in the last 30 seconds?"
`get_request_details()`	Ask AI: "Show me the headers and payload for that login request"
`get_response_content()`	Ask AI: "What data did the server return from that API call?"
`modify_headers()`	Ask AI: "Add custom authentication headers to all requests"
`spawn_browser(block_resources=[...])`	Ask AI: "Block all tracking scripts and ads"

Dynamic Network Hook System (NEW!)

🎯 AI writes custom Python functions to intercept and modify requests/responses in real-time!

Tool	Description
`create_dynamic_hook()`	Ask AI: "Create a hook that blocks ads and logs API calls"
`create_simple_dynamic_hook()`	Ask AI: "Block all requests to .ads.com"*
`list_dynamic_hooks()`	Ask AI: "Show me all active hooks with statistics"
`get_dynamic_hook_details()`	Ask AI: "Show me the Python code for hook ID abc123"
`remove_dynamic_hook()`	Ask AI: "Remove the ad blocking hook"

AI Hook Learning System

Tool	Description
`get_hook_documentation()`	AI learns request object structure and HookAction types
`get_hook_examples()`	10 detailed examples: blockers, redirects, API proxies, custom responses
`get_hook_requirements_documentation()`	Pattern matching, conditions, best practices
`get_hook_common_patterns()`	Ad blocking, API proxying, auth injection patterns
`validate_hook_function()`	Validate hook Python code before deployment

💡 Example: "Create a hook that blocks social media trackers during work hours, redirects old API endpoints to new servers, and adds authentication headers to all API calls"

🔥 Hook Features:

Real-time processing (no pending state)
AI-generated Python functions with custom logic
Pattern matching with wildcards and conditions
Request/response stage processing with content modification
Full response body replacement and header injection
Automatic syntax validation and error handling
Base64 encoding for binary content support

CDP Function Execution

Tool	Description
`execute_cdp_command()`	Direct CDP commands (use snake_case)
`discover_global_functions()`	Find JavaScript functions
`discover_object_methods()`	Discover object methods (93+ methods)
`call_javascript_function()`	Execute any function
`inject_and_execute_script()`	Run custom JS code
`inspect_function_signature()`	Inspect function details
`create_persistent_function()`	Functions that survive reloads
`execute_function_sequence()`	Execute function sequences
`create_python_binding()`	Create Python-JS bindings
`execute_python_in_browser()`	Execute Python code via py2js
`get_execution_contexts()`	Get JS execution contexts
`list_cdp_commands()`	List available CDP commands
`get_function_executor_info()`	Get executor state info

Progressive Element Cloning

Tool	Description
`clone_element_progressive()`	Initial lightweight structure
`expand_styles()`	On-demand styles expansion
`expand_events()`	On-demand events expansion
`expand_children()`	Progressive children expansion
`expand_css_rules()`	Expand CSS rules data
`expand_pseudo_elements()`	Expand pseudo-elements
`expand_animations()`	Expand animations data
`list_stored_elements()`	List stored elements
`clear_stored_element()`	Clear specific element
`clear_all_elements()`	Clear all stored elements

Cookie & Storage

Tool	Description
`get_cookies()`	Read cookies
`set_cookie()`	Set cookies
`clear_cookies()`	Clear cookies
`get_instance_state()`	localStorage & sessionStorage snapshot
`execute_script()`	Read/modify storage via JS

Tabs

Tool	Description
`list_tabs()`	List open tabs
`new_tab()`	Create new tab
`switch_tab()`	Change active tab
`close_tab()`	Close tab
`get_active_tab()`	Get current tab

Page Analysis & Debugging

Tool	Description
`take_screenshot()`	Capture screenshots
`get_page_content()`	HTML and metadata
`get_debug_view()`	Debug info with pagination
`clear_debug_view()`	Clear debug logs
`export_debug_logs()`	Export logs (JSON/pickle/gzip)
`get_debug_lock_status()`	Debug lock status
`validate_browser_environment_tool()`	NEW! Diagnose platform issues & browser compatibility

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

Spawned undetectable browser instance
Navigated to augmentcode.com
Identified hero section using DOM analysis
Extracted complete element with all styles, structure, and assets
Generated pixel-perfect HTML recreation with inline CSS
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 ROADMAP.md. Contributions welcome.

Contributing

We love first‑time contributions. Read CONTRIBUTING.md 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 LICENSE.

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

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github		.github
demo		demo
examples		examples
media		media
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMPARISON.md		COMPARISON.md
CONTRIBUTING.md		CONTRIBUTING.md
Checklist.md		Checklist.md
Dockerfile		Dockerfile
HALL_OF_FAME.md		HALL_OF_FAME.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run_server.bat		run_server.bat
run_server.sh		run_server.sh
smithery.yaml		smithery.yaml

Uh oh!

License

vibheksoni/stealth-browser-mcp

Folders and files

Latest commit

History

Repository files navigation

Stealth Browser MCP

🎥 See It In Action

🔗 Quick Links

Quickstart (60 seconds)

✅ Recommended Setup (Creator's Tested Method)

⚠️ Alternative: FastMCP CLI (Untested by Creator)

Alternative: Manual Configuration (If Claude CLI not available)

🎛️ NEW: Customize Your Installation

Quick Test

🚨 Common Installation Issues

✨ Why developers star this

🎯 NEW: Advanced Text Input

⚡ Instant Text Pasting

📝 Smart Newline Handling

🔧 Why This Matters

🛡️ NEW: Cross-Platform Compatibility & Root Support

⚙️ Smart Environment Detection

🔧 Flexible Args Handling

📊 Built-in Diagnostics

🎯 Why This Matters

🎛️ Modular Architecture

⚙️ Installation Modes

📦 Tool Sections

🆚 Stealth vs Playwright MCP

Toolbox

Basic Network Monitoring

Dynamic Network Hook System (NEW!)

AI Hook Learning System

🎨 Featured Demo: Augment Code Hero Clone

User Prompt:

What Claude Did Automatically:

Result:

Key Features Demonstrated:

🧪 Real‑world examples

🛣️ Roadmap

Contributing

💼 Need Website or App Development? Try DevHive Studios

🏆 Why DevHive?

🛠️ Services Available

☕ Support This Project

📄 License

⭐ Star History

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Sponsor this project

Uh oh!

Contributors 2

Uh oh!

Languages