Skip to content

Stealth browser automation for AI agents over MCP and the Chrome DevTools Protocol: navigation, network hooks, DOM extraction, and pixel-accurate UI cloning.

Rewrite README: remove duplication, trim emojis, update Discord link

Vibhek Soni166aef628533
diff --git a/README.md b/README.md
index 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).
-[![MCP](https://img.shields.io/badge/MCP-Claude-blue?style=flat-square)](https://modelcontextprotocol.io)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
[![Stars](https://img.shields.io/github/stars/vibheksoni/stealth-browser-mcp?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/stargazers)
-[![Forks](https://img.shields.io/github/forks/vibheksoni/stealth-browser-mcp?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/network/members)
-[![Issues](https://img.shields.io/github/issues/vibheksoni/stealth-browser-mcp?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/issues)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](CONTRIBUTING.md)
-[![Discord](https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/7ETmqgTY6H)
-[![Tools](https://img.shields.io/badge/Tools-90-orange?style=flat-square)](#-toolbox)
-[![Success Rate](https://img.shields.io/badge/Success%20Rate-98.7%25-success?style=flat-square)](#-stealth-vs-playwright-mcp)
-[![Cloudflare Bypass](https://img.shields.io/badge/Cloudflare-Bypass-red?style=flat-square)](#-why-developers-star-this)
[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/secrets)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](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 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
+# 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):**
-```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:
```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",
- "--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-hooks
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
+**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
+## License
MIT β€” 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">
[![Star History Chart](https://api.star-history.com/svg?repos=vibheksoni/stealth-browser-mcp&type=Date)](https://www.star-history.com/#vibheksoni/stealth-browser-mcp&Date)
+
+</div>