Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.
Python ai-agent-toolsai-toolsanthropicanti-bot-bypassautomation-toolsbrowser-automationchrome-devtoolsclaude-mcpcloudflare-bypassdeveloper-toolsfastmcpmcp-servermodel-context-protocolnetwork-interceptionnodriverpythonstealth-browserundetectable-browserweb-automationweb-scraping
Rewrite README: remove duplication, trim emojis, update Discord link
Vibhek Soni166aef628533
diff --git a/README.md b/README.mdindex c882cda..5aad5d3 100644--- a/README.md+++ b/README.md@@ -4,391 +4,189 @@# Stealth Browser MCP-**π The ONLY browser automation that bypasses Cloudflare, antibots, and social media blocks**+**Undetectable browser automation for MCP-compatible AI agents.**-</div>--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**+Bypass Cloudflare, antibot systems, and social media blocks with real browser instances powered by [nodriver](https://github.com/ultrafunkamsterdam/nodriver) + Chrome DevTools Protocol + [FastMCP](https://github.com/jlowin/fastmcp).-[](https://modelcontextprotocol.io)+[](https://modelcontextprotocol.io)[](https://github.com/vibheksoni/stealth-browser-mcp/stargazers)-[](https://github.com/vibheksoni/stealth-browser-mcp/network/members)-[](https://github.com/vibheksoni/stealth-browser-mcp/issues)-[](CONTRIBUTING.md)-[](https://discord.gg/7ETmqgTY6H)-[](#-toolbox)-[](#-stealth-vs-playwright-mcp)-[](#-why-developers-star-this)[](LICENSE)+[](https://discord.gg/secrets)+[](CONTRIBUTING.md)++</div>++----> Give your AI agent real browser superpowers: access Cloudflare sites, extract any UI, and intercept network traffic β from inside your chat.+## Table of Contents++- [Demo](#demo)+- [Features](#features)+- [Quickstart](#quickstart)+- [Modular Architecture](#modular-architecture)+- [Toolbox](#toolbox)+- [Stealth vs Playwright MCP](#stealth-vs-playwright-mcp)+- [Troubleshooting](#troubleshooting)+- [Examples](#examples)+- [Showcase](#showcase)+- [Roadmap](#roadmap)+- [Contributing](#contributing)+- [Support](#support)+- [License](#license)-## π₯ **See It In Action**+---++## Demo<div align="center">-<img src="media/showcase-demo-full.gif" alt="Stealth Browser MCP Demo" width="800" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">+<img src="media/showcase-demo-full.gif" alt="Stealth Browser MCP Demo" width="800" style="border-radius: 8px;"><br><br><a href="media/Showcase%20Stealth%20Browser%20Mcp.mp4" download>- <img src="https://img.shields.io/badge/πΉ-Watch%20HD%20Video-red?style=for-the-badge&logo=video&logoColor=white" alt="Watch HD Video">+ <img src="https://img.shields.io/badge/Watch%20HD%20Video-red?style=for-the-badge&logo=video&logoColor=white" alt="Watch HD Video"></a></div>-*π― **Watch**: Stealth Browser MCP bypassing Cloudflare, cloning UI elements, and intercepting network traffic β all through simple AI chat commands*+*Stealth Browser MCP bypassing Cloudflare, cloning UI elements, and intercepting network traffic β all through AI chat commands.*----## π Quick Links+## Features-- βΆοΈ [Quickstart](#quickstart-60-seconds)-- π [Hall of Fame](HALL_OF_FAME.md) - Impossible automations made possible-- π₯ [Stealth vs Others](COMPARISON.md) - Why we dominate the competition-- π₯ [Viral Examples](examples/claude_prompts.md) - Copy & paste prompts that blow minds-- π§° [90 Tools](#toolbox) - Complete arsenal of browser automation-- π₯ [Live Demos](demo/) - See it bypass what others can't-- π€ [Contributing](#contributing) & π¬ [Discord](https://discord.gg/7ETmqgTY6H)+- **Antibot bypass** β Works on Cloudflare, Queue-It, and other protection systems that block traditional automation+- **90 tools across 11 sections** β From basic navigation to advanced CDP function execution+- **Modular loading** β Run the full 90-tool arsenal or a minimal 22-tool core; disable what you don't need+- **Pixel-accurate element cloning** β Extract complete elements with all CSS, DOM structure, events, and assets via CDP+- **Network interception** β Inspect every request, response, header, and payload through your AI agent+- **Dynamic hook system** β AI-generated Python functions that intercept and modify network traffic in real-time+- **Instant text input** β Paste large content via CDP or type with human-like keystrokes and newline support+- **Cross-platform** β Windows, macOS, Linux, Docker, and CI/CD pipelines with automatic environment detection+- **Browser support** β Chrome, Chromium, and Microsoft Edge (automatic detection)+- **Clean MCP integration** β No custom brokers or wrappers; works with Claude Code, Claude Desktop, Cursor, and any MCP client----## Quickstart (60 seconds)+## Quickstart++### 1. Clone and install-### β **Recommended Setup (Creator's Tested Method)**```bash-# 1. Clone the repositorygit clone https://github.com/vibheksoni/stealth-browser-mcp.gitcd stealth-browser-mcp--# 2. Create virtual environmentpython -m venv venv-# 3. Activate virtual environment+# Activate virtual environment# Windows:venv\Scripts\activate# Mac/Linux:source venv/bin/activate-# 4. Install dependenciespip install -r requirements.txt--# 5. Add to Claude Code using CLI```-**Windows (Full Installation):**-```bash-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\"]}"-```+### 2. Add to your MCP client-**Windows (Minimal - Core Tools Only):**-```bash-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\"]}"-```+**Claude Code CLI (recommended):**-**Mac/Linux (Full Installation):**+Windows:```bash-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"- ]-}'+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\"]}"```-**Mac/Linux (Custom - Disable Advanced Features):**+Mac/Linux:```bashclaude 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"- ]+ "args": ["/path/to/stealth-browser-mcp/src/server.py"]}'```-> **π‘ Replace `/path/to/stealth-browser-mcp/` with your actual project path**-------### β οΈ **Alternative: FastMCP CLI (Untested by Creator)**+> Replace `/path/to/stealth-browser-mcp/` with your actual project path.-*These methods should theoretically work but have not been tested by the creator. Use at your own risk.*--```bash-# 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:+<details>+<summary><strong>Manual JSON configuration (Claude Desktop, Cursor, etc.)</strong></summary>-**Claude Desktop - Windows** (`%APPDATA%\Claude\claude_desktop_config.json`)+Windows (`%APPDATA%\Claude\claude_desktop_config.json`):```json{"mcpServers": {- "stealth-browser-full": {+ "stealth-browser-mcp": {"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`)+Mac/Linux (`~/Library/Application Support/Claude/claude_desktop_config.json`):```json{"mcpServers": {- "stealth-browser-full": {+ "stealth-browser-mcp": {"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**+</details>-Stealth Browser MCP now supports modular tool loading! Disable sections you don't need:+<details>+<summary><strong>FastMCP CLI (untested)</strong></summary>```bash-# 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](https://github.com/ultrafunkamsterdam/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**-```python-# 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**-```python-# 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**-```python-# NEW: Automatic privilege detection and sandbox handling-validate_browser_environment_tool() # Diagnose your environment+pip install fastmcp+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```-- **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**-```json-// 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+</details>-### π **Built-in Diagnostics**-```bash-# 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+### 3. Test it-### π― **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+Restart your MCP client and ask your agent:-**Real-world impact**: Browser spawning now works reliably across all environments - from local development to production containers to CI/CD pipelines.+> "Use stealth-browser to navigate to https://example.com and take a screenshot."----## ποΈ **Modular Architecture**+## Modular Architecture-**NEW in v0.2.2**: Stealth Browser MCP now supports modular tool loading! Choose exactly what functionality you need:--### **βοΈ Installation Modes**+Choose exactly what functionality you need. Run the full 90-tool suite or strip it down to 22 core tools.| 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**+| **Full** (default) | 90 | Complete browser automation and debugging |+| **Minimal** (`--minimal`) | 22 | Core browser automation only |+| **Custom** (`--disable-*`) | Your choice | Disable specific sections |```bash-# List all sections with tool counts+python src/server.py --minimal+python src/server.py --disable-cdp-functions --disable-dynamic-hookspython 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+**Available sections:**-| 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+| Section | Tools | Description |+|---------|-------|-------------|+| `browser-management` | 11 | Core browser operations |+| `element-interaction` | 11 | Page interaction and manipulation |+| `element-extraction` | 9 | Element cloning and extraction |+| `file-extraction` | 9 | File-based extraction tools |+| `network-debugging` | 5 | Network monitoring and interception |+| `cdp-functions` | 13 | Chrome DevTools Protocol execution |+| `progressive-cloning` | 10 | Advanced element cloning |+| `cookies-storage` | 3 | Cookie and storage management |+| `tabs` | 5 | Tab management |+| `debugging` | 6 | Debug and system tools |+| `dynamic-hooks` | 10 | AI-powered network hooks |---@@ -405,7 +203,7 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank| `list_instances()` | Manage multiple sessions || `get_instance_state()` | Full browser state information || `go_back()` | Navigate back in history |-| `go_forward()` | Navigate forward 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 |@@ -420,7 +218,7 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank| `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 |+| `paste_text()` | Instant text pasting via CDP || `scroll_page()` | Natural scrolling || `wait_for_element()` | Smart waiting || `execute_script()` | Run JavaScript |@@ -430,7 +228,7 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank</details><details>-<summary><strong>Element Extraction (CDPβaccurate)</strong></summary>+<summary><strong>Element Extraction (CDP-accurate)</strong></summary>| Tool | Description ||------|-------------|@@ -464,49 +262,25 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank</details><details>-<summary><strong>Network Debugging & Interception</strong></summary>--**π΅οΈ 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!**+<summary><strong>Network Debugging and Interception</strong></summary>| 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+| `list_network_requests()` | List captured network requests |+| `get_request_details()` | Inspect headers and payload for a request |+| `get_response_content()` | Get response data from a request |+| `modify_headers()` | Add custom headers to requests |+| `spawn_browser(block_resources=[...])` | Block tracking scripts, ads, etc. |+| `create_dynamic_hook()` | Create Python functions to intercept/modify requests |+| `create_simple_dynamic_hook()` | Quick hook creation with presets |+| `list_dynamic_hooks()` | List active hooks with statistics |+| `get_dynamic_hook_details()` | Inspect hook source code |+| `remove_dynamic_hook()` | Remove a hook |+| `get_hook_documentation()` | Request object structure and HookAction types |+| `get_hook_examples()` | 10 detailed examples: blockers, redirects, proxies |+| `get_hook_requirements_documentation()` | Pattern matching and best practices |+| `get_hook_common_patterns()` | Ad blocking, API proxying, auth injection |+| `validate_hook_function()` | Validate hook code before deployment |</details>@@ -550,14 +324,14 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank</details><details>-<summary><strong>Cookie & Storage</strong></summary>+<summary><strong>Cookie and Storage</strong></summary>| Tool | Description ||------|-------------|| `get_cookies()` | Read cookies || `set_cookie()` | Set cookies || `clear_cookies()` | Clear cookies |-| `get_instance_state()` | localStorage & sessionStorage snapshot |+| `get_instance_state()` | localStorage and sessionStorage snapshot || `execute_script()` | Read/modify storage via JS |</details>@@ -576,7 +350,7 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank</details><details>-<summary><strong>Page Analysis & Debugging</strong></summary>+<summary><strong>Page Analysis and Debugging</strong></summary>| Tool | Description ||------|-------------|@@ -586,121 +360,109 @@ Sites users care about: LinkedIn β’ Instagram β’ Twitter/X β’ Amazon β’ Bank| `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 |+| `validate_browser_environment_tool()` | Diagnose platform issues and browser compatibility |</details>----## π¨ **Featured Demo: Augment Code Hero Clone**+## Stealth vs Playwright MCP-<div align="center">-<img src="media/AugmentHeroClone.PNG" alt="Augment Code Hero Recreation" width="700" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">-<br><br>-<a href="demo/augment-hero-recreation.html">- <img src="https://img.shields.io/badge/π-View%20Live%20Demo-blue?style=for-the-badge" alt="View Live Demo">-</a>-</div>+| Feature | Stealth Browser MCP | Playwright MCP |+|---------|---------------------|----------------|+| Cloudflare / Queue-It | Consistently bypasses | Commonly blocked |+| Banking / Gov portals | Works | Frequently blocked |+| Social media automation | Full automation | Captchas and bans |+| UI element cloning | CDP-accurate extraction | Limited |+| Network debugging | Full request/response inspection via AI | Basic |+| API reverse engineering | Payload inspection through chat | Manual tools only |+| Dynamic hook system | AI-generated Python functions for real-time interception | Not available |+| Modular architecture | 11 sections, 22β90 tools | Fixed ~20 tools |+| Total tools | 90 (customizable) | ~20 |++Tested on: LinkedIn, Instagram, Twitter/X, Amazon, banking portals, government sites, Cloudflare-protected APIs, Nike SNKRS, Ticketmaster, Supreme.-**π― 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/"*+## Troubleshooting-### **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+**No compatible browser found**+Install Chrome, Chromium, or Microsoft Edge. The server auto-detects the first available browser. Run `validate_browser_environment_tool()` to diagnose.-### **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+**Tools hang or return malformed JSON**+Debug output was printing to stdout, corrupting the MCP JSON-RPC protocol. This was fixed in [#8](https://github.com/vibheksoni/stealth-browser-mcp/issues/8). Pull the latest `master` branch.-**The entire process took under 2 minutes of AI conversation!**+**Browser crashes on Linux / Docker / CI**+Run with `--sandbox=false` or ensure your environment supports sandboxing. The server auto-detects root and container environments and adjusts accordingly.-### **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+**Too many tools cluttering the AI chat**+Use `--minimal` for 22 core tools, or selectively disable sections:+```bash+python src/server.py --disable-cdp-functions --disable-dynamic-hooks --disable-progressive-cloning+```-**π‘ This showcases the real power of Stealth Browser MCP - turning complex web cloning tasks into simple AI conversations.**+**Module not found errors**+Make sure you activated the virtual environment and installed dependencies:+```bash+pip install -r requirements.txt+```----## π§ͺ Realβworld examples+## 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+- **Market research** β Extract pricing and features from competitors, output a comparison table+- **UI cloning** β Recreate a pricing section with exact fonts, styles, and interactions+- **Inventory monitoring** β Watch a product page and alert when stock changes+- **API reverse engineering** β Intercept requests, map endpoints, and inspect data flow-You can drive all of the above from a single AI agent chat.+All driven from a single AI agent conversation.----## π£οΈ Roadmap+## Showcase-See the live plan in [ROADMAP.md](ROADMAP.md). Contributions welcome.-------## Contributing+<div align="center">+<img src="media/AugmentHeroClone.PNG" alt="Augment Code Hero Recreation" width="700" style="border-radius: 8px;">+</div>-We love firstβtime contributions. Read [CONTRIBUTING.md](CONTRIBUTING.md) and open a PR.+**Augment Code hero clone** β A user asked Claude to clone the hero section from [augmentcode.com](https://www.augmentcode.com/). The agent spawned a stealth browser, navigated to the site, extracted the complete element via CDP (styles, structure, assets), and generated a pixel-accurate HTML recreation with responsive design and animations. The entire process took under two minutes of conversation.-If this project saves you time, consider starring the repo and sharing it with a friend.+[View the recreation](demo/augment-hero-recreation.html) | [Full walkthrough](demo/augment-hero-clone.md)----## πΌ Need Website or App Development? Try DevHive Studios+## Roadmap-**DevHive Studios** is a fair marketplace connecting businesses with skilled developers. Unlike other platforms, we put developers first while keeping costs affordable for clients.+See the live plan in [ROADMAP.md](ROADMAP.md). Contributions welcome.-### π **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+## Contributing-**Ready to start your project?** Hit up DevHive Studios today:-- π [devhivestudios.com](https://devhivestudios.com)-- π¬ [Contact on Discord](https://discord.gg/mUcj5kwfrd)+Read [CONTRIBUTING.md](CONTRIBUTING.md) and open a PR. First-time contributors welcome.-*DevHive Studios β Fair marketplace. Quality results.*+If this project saves you time, star the repo β it helps more than you think.----## β Support This Project+## Support-If this browser automation MCP saved you time or made you money, consider supporting the development:--- **β Buy me a coffee**: [buymeacoffee.com/vibheksoni](https://buymeacoffee.com/vibheksoni)--*Every contribution helps maintain and improve this project! π*+If this tool saved you time or made you money, consider supporting development:+- [Buy me a coffee](https://buymeacoffee.com/vibheksoni)+- [Join the Discord](https://discord.gg/secrets)----## π License+## LicenseMIT β see [LICENSE](LICENSE).----If you want your AI agent to access ANY website, star this repo. It helps more than you think.-------## β Star History+<div align="center">[](https://www.star-history.com/#vibheksoni/stealth-browser-mcp&Date)++</div>