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
Refresh README: new logo, NodeMaven sponsorship, corrected tool docs, tightened claims
Vibhek Soni8d234b4d6367
diff --git a/.gitignore b/.gitignoreindex d5afe64..c03ef32 100644--- a/.gitignore+++ b/.gitignore@@ -235,16 +235,15 @@ $RECYCLE.BIN/# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)-_ignore/-oldstuff/-old_network_hook_system/-element_clones/-testing/-.claude-requirements_frozen.txt-ignore/-.oclaude/-CLAUDE.md-AGENTS.md-.mcp.json-Checklist.md\ No newline at end of file++.*/+.*.json+*.md+!README.md+!ROADMAP.md+!HALL_OF_FAME.md+!CHANGELOG.md+!CODE_OF_CONDUCT.md+!COMPARISON.md+!CONTRIBUTING.md+!SECURITY.md\ No newline at end of filediff --git a/README.md b/README.mdindex 44f26be..c52ad97 100644--- a/README.md+++ b/README.md@@ -1,29 +1,70 @@<div align="center">-<img src="media/UndetectedStealthBrowser.png" alt="Stealth Browser MCP" width="200"/>+<img src="media/UndetectedStealthBrowser-2.png" alt="Stealth Browser MCP logo" width="200"/># Stealth Browser MCP-**Undetectable browser automation for MCP-compatible AI agents.**+**Stealth browser automation for MCP-compatible AI agents.**-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).+Navigate Cloudflare challenges, anti-bot checks, and login walls with real Chrome-family browser instances powered by [nodriver](https://github.com/ultrafunkamsterdam/nodriver), Chrome DevTools Protocol, and [FastMCP](https://github.com/jlowin/fastmcp).[](https://modelcontextprotocol.io)+[](pyproject.toml)+[](pyproject.toml)[](https://github.com/vibheksoni/stealth-browser-mcp/stargazers)[](LICENSE)-[](https://discord.gg/secrets)[](CONTRIBUTING.md)</div>---+## Sponsored by NodeMaven++<table>+<tr>+<td align="center" width="200">++<a href="https://go.nodemaven.com/stealthbrowsermcpGH"><img src="media/nodemaven-sponsor.png" alt="NodeMaven" width="180"></a>++</td>+<td>++[NodeMaven](https://go.nodemaven.com/stealthbrowsermcpGH) is a proxy provider offering high-quality IPs for browser automation, web scraping, SEO research, and social media management.++**Why NodeMaven?**++- 99.9% uptime+- Sticky sessions for up to 7 days+- IP filtering with proxy fraud scores below 97%+- No KYC required+- Traffic cashback with up to 10% returned based on GB usage++**Special discounts for stealth-browser-mcp users**++- `STEALTHMCP35` — 35% off Mobile and Residential Proxies+- `STEALTHMCP40` or `STEALTHMCP 40` — 40% off ISP Static Proxies. If one version is not accepted, try the other.++[Get started with NodeMaven](https://go.nodemaven.com/stealthbrowsermcpGH)++</td>+</tr>+</table>++> Sponsored placement. NodeMaven is a paid sponsor of this project.++---+## Table of Contents+- [Sponsored by NodeMaven](#sponsored-by-nodemaven)- [Demo](#demo)- [Features](#features)- [Quickstart](#quickstart)+- [Agent Skill](#agent-skill)+- [Trust Model](#trust-model)- [Modular Architecture](#modular-architecture)+- [Server Configuration](#server-configuration)- [Toolbox](#toolbox)- [Stealth vs Playwright MCP](#stealth-vs-playwright-mcp)- [Troubleshooting](#troubleshooting)@@ -39,29 +80,30 @@ Bypass Cloudflare, antibot systems, and social media blocks with real browser in## Demo<div align="center">-<img src="media/showcase-demo-full.gif" alt="Stealth Browser MCP Demo" width="800" style="border-radius: 8px;">+<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"></a></div>-*Stealth Browser MCP bypassing Cloudflare, cloning UI elements, and intercepting network traffic — all through AI chat commands.*+*Stealth Browser MCP passing a Cloudflare challenge, cloning UI elements, and inspecting network traffic through AI chat commands.*---## Features-- **Antibot bypass** — Works on Cloudflare, Queue-It, and other protection systems that block traditional automation-- **97 tools across 11 sections** — From basic navigation to advanced CDP function execution-- **Modular loading** — Run the full 97-tool arsenal or a minimal 20-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+- **Anti-bot resistance** - Has passed Cloudflare and Queue-It style challenges in testing; results vary by site, region, browser version, and detector version.+- **97 tools across 11 sections** - From basic navigation to advanced CDP function execution.+- **Modular loading** - Run the full 97-tool surface or a minimal 20-tool core; disable sections you do not need.+- **Pixel-accurate element cloning** - Extract complete elements with CSS, DOM structure, events, animations, and assets via CDP.+- **Network inspection** - Inspect requests, responses, headers, payloads, and captured bodies through your AI agent.+- **Dynamic hook system** - Restricted Python hooks can intercept, block, redirect, fulfill, or modify request/response flows.+- **CDP execution** - Run JavaScript, direct CDP commands, and pre-document scripts through trusted local MCP clients.+- **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 environments with automatic browser/platform detection.+- **Browser support** - Chrome, Chromium, and Microsoft Edge with automatic executable discovery.+- **Clean MCP integration** - Works through standard MCP clients without custom brokers.---@@ -69,15 +111,17 @@ Bypass Cloudflare, antibot systems, and social media blocks with real browser in### 1. Clone and install+Requires Python 3.10+ and Chrome, Chromium, or Microsoft Edge.+```bashgit clone https://github.com/vibheksoni/stealth-browser-mcp.gitcd stealth-browser-mcppython -m venv venv-# Activate virtual environment-# Windows:+# Windowsvenv\Scripts\activate-# Mac/Linux:++# macOS / Linuxsource venv/bin/activatepip install -r requirements.txt@@ -88,11 +132,13 @@ pip install -r requirements.txt**Claude Code CLI (recommended):**Windows:-```bash++```powershellclaude 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:+macOS / Linux:+```bashclaude mcp add-json stealth-browser-mcp '{"type": "stdio",@@ -101,12 +147,13 @@ claude mcp add-json stealth-browser-mcp '{}'```-> Replace `/path/to/stealth-browser-mcp/` with your actual project path.+Replace the example path with your real clone path.<details><summary><strong>Manual JSON configuration (Claude Desktop, Cursor, etc.)</strong></summary>Windows (`%APPDATA%\Claude\claude_desktop_config.json`):+```json{"mcpServers": {@@ -119,7 +166,8 @@ Windows (`%APPDATA%\Claude\claude_desktop_config.json`):}```-Mac/Linux (`~/Library/Application Support/Claude/claude_desktop_config.json`):+macOS / Linux (`~/Library/Application Support/Claude/claude_desktop_config.json`):+```json{"mcpServers": {@@ -135,14 +183,14 @@ Mac/Linux (`~/Library/Application Support/Claude/claude_desktop_config.json`):</details><details>-<summary><strong>FastMCP CLI (untested)</strong></summary>+<summary><strong>Experimental FastMCP CLI install</strong></summary>++These commands are provided for users who prefer FastMCP's installer. The stdio JSON setup above is the recommended path.```bashpip install fastmcpfastmcp install claude-desktop src/server.py --with-requirements requirements.txt-# ORfastmcp install claude-code src/server.py --with-requirements requirements.txt-# ORfastmcp install cursor src/server.py --with-requirements requirements.txt```@@ -152,9 +200,11 @@ fastmcp install cursor src/server.py --with-requirements requirements.txtRestart your MCP client and ask your agent:-> "Use stealth-browser to navigate to https://example.com and take a screenshot."+> Use stealth-browser to navigate to https://example.com and take a screenshot.++----### Agent Skill+## Agent SkillThis repo includes an agent skill at `skills/stealth-browser-mcp` for clients that support Codex-style skills. It teaches agents the recommended tool order, state checks, pre-document CDP script usage, network debugging flow, and browser cleanup rules.@@ -162,43 +212,56 @@ Use the skill when an LLM struggles to choose the right MCP tool or forgets to v---+## Trust Model++This server exposes powerful local browser-control primitives: CDP execution, page JavaScript execution, cookie/storage access, network interception, dynamic hooks, header mutation, navigation, and file uploads from allowlisted local paths.++Treat the MCP client or agent as the security principal. The recommended deployment is local `stdio` transport with a trusted desktop MCP client. If you use HTTP transport, set `STEALTH_BROWSER_MCP_AUTH_TOKEN` and do not expose unauthenticated HTTP outside trusted local or private networks.++---+## Modular Architecture-Choose exactly what functionality you need. Run the full 97-tool suite or strip it down to 20 core tools.+Choose exactly what functionality you need. Run the full 97-tool suite or strip it down to the 20-tool core.| Mode | Tools | Use Case ||------|-------|----------|| **Full** (default) | 97 | Complete browser automation and debugging |-| **Minimal** (`--minimal`) | 20 | Core browser automation only |+| **Minimal** (`--minimal`) | 20 | Core browser automation and interaction || **Custom** (`--disable-*`) | Your choice | Disable specific sections |+| **Xpool safe** (`--xpool-safe`) | 83 | Disable CDP function tools that trigger `Runtime.enable` |```bashpython src/server.py --minimalpython src/server.py --disable-cdp-functions --disable-dynamic-hookspython src/server.py --list-sectionspython src/server.py --debug+python src/server.py --transport http --host 127.0.0.1 --port 8000```-Use `--debug` or set `STEALTH_BROWSER_DEBUG=1` to enable verbose server diagnostics on `stderr`. In normal MCP `stdio` usage, debug logging stays quiet by default to avoid noisy transport output.+Use `--debug` or set `STEALTH_BROWSER_DEBUG=1` to enable verbose server diagnostics on `stderr`. Normal MCP `stdio` runs stay quiet by default to avoid corrupting JSON-RPC transport output.-**HTTP transport security**-- `stdio` transport is recommended for local MCP clients and does not require HTTP auth.-- HTTP transport remains unauthenticated by default for backward compatibility.-- Do not expose unauthenticated HTTP transport outside trusted local or private networks.-- Set `STEALTH_BROWSER_MCP_AUTH_TOKEN` to enable bearer-token auth for HTTP transport.-- Clients must send `Authorization: Bearer <token>` after HTTP auth is enabled.+**Available sections:**-**Browser lifecycle defaults**-- Idle browser instances are reaped automatically after 10 minutes by default.-- Override per instance with `spawn_browser(idle_timeout_seconds=...)`.-- Disable idle reaping globally with `BROWSER_IDLE_TIMEOUT=0`.-- Tune the background reaper cadence with `BROWSER_IDLE_REAPER_INTERVAL`.-- Tune startup cleanup of abandoned temp profiles with `BROWSER_ORPHAN_PROFILE_MAX_AGE` (seconds).-- Restrict local file uploads with `BROWSER_FILE_UPLOAD_ALLOWED_DIRS`.+| Section | Tools | Description |+|---------|-------|-------------|+| `browser-management` | 8 | Core browser operations |+| `element-interaction` | 12 | Page interaction and manipulation |+| `element-extraction` | 9 | Element cloning and extraction |+| `file-extraction` | 9 | File-based extraction tools |+| `network-debugging` | 10 | Network monitoring and capture |+| `cdp-functions` | 14 | Chrome DevTools Protocol execution |+| `progressive-cloning` | 10 | Advanced element cloning |+| `cookies-storage` | 3 | Cookie management |+| `tabs` | 5 | Tab management |+| `debugging` | 7 | Debug and system tools |+| `dynamic-hooks` | 10 | AI-assisted network hooks |-### Server Environment Variables+----These are regular environment variables for the MCP server process itself. Set them wherever you launch `src/server.py`:+## Server Configuration++These are environment variables for the MCP server process. Set them in your shell, service manager, Docker environment, or MCP client `env` block.| Variable | Default | Meaning ||----------|---------|---------|@@ -206,25 +269,16 @@ These are regular environment variables for the MCP server process itself. Set t| `MCP_AUTH_TOKEN` | unset | Backward-compatible alias for `STEALTH_BROWSER_MCP_AUTH_TOKEN`. || `BROWSER_IDLE_TIMEOUT` | `600` | Global idle timeout in seconds before an unused browser instance is auto-closed. Set `0` to disable idle reaping globally. || `BROWSER_IDLE_REAPER_INTERVAL` | `60` | Background reaper check interval in seconds. |-| `BROWSER_ORPHAN_PROFILE_MAX_AGE` | `21600` | Startup cleanup threshold in seconds for stale `uc_*` temp profiles that are not in use by live browser processes. Set `0` to disable this startup sweep. |+| `BROWSER_ORPHAN_PROFILE_MAX_AGE` | `21600` | Startup cleanup threshold in seconds for stale `uc_*` temp profiles. Set `0` to disable this startup sweep. || `BROWSER_FILE_UPLOAD_ALLOWED_DIRS` | repo root | Directories that `file_upload()` may read from. Separate multiple roots with `;` on Windows or `:` on macOS/Linux. || `STEALTH_BROWSER_DEBUG` | `0` | Enable verbose debug logging to `stderr` when set to `1`. |+| `DEBUG` | `0` | Legacy alias for `STEALTH_BROWSER_DEBUG`. |+| `XPOOL_SAFE_MODE` | `0` | Disable the `cdp-functions` section at startup. |+| `PORT` | `8000` | Default HTTP port when `--port` is not provided. |-**Where to set them**--- **Shell / local terminal**-```bash-# macOS / Linux-export STEALTH_BROWSER_MCP_AUTH_TOKEN="replace-with-a-long-random-token"-export BROWSER_IDLE_TIMEOUT=900-export BROWSER_IDLE_REAPER_INTERVAL=30-export BROWSER_ORPHAN_PROFILE_MAX_AGE=43200-export BROWSER_FILE_UPLOAD_ALLOWED_DIRS="/Users/me/uploads:/Users/me/Documents"-python src/server.py-```+**PowerShell example:**```powershell-# Windows PowerShell$env:STEALTH_BROWSER_MCP_AUTH_TOKEN='replace-with-a-long-random-token'$env:BROWSER_IDLE_TIMEOUT='900'$env:BROWSER_IDLE_REAPER_INTERVAL='30'@@ -233,8 +287,7 @@ $env:BROWSER_FILE_UPLOAD_ALLOWED_DIRS='C:\Users\me\uploads;C:\Users\me\Documentspython src/server.py```-- **MCP client config**- Put them in the server `env` block for your client.+**MCP client `env` block:**```json{@@ -245,8 +298,6 @@ python src/server.py"env": {"STEALTH_BROWSER_MCP_AUTH_TOKEN": "replace-with-a-long-random-token","BROWSER_IDLE_TIMEOUT": "900",- "BROWSER_IDLE_REAPER_INTERVAL": "30",- "BROWSER_ORPHAN_PROFILE_MAX_AGE": "43200","BROWSER_FILE_UPLOAD_ALLOWED_DIRS": "C:\\Users\\me\\uploads;C:\\Users\\me\\Documents"}}@@ -254,234 +305,209 @@ python src/server.py}```-- **systemd / long-running service**-```ini-[Service]-Environment="STEALTH_BROWSER_MCP_AUTH_TOKEN=replace-with-a-long-random-token"-Environment="BROWSER_IDLE_TIMEOUT=900"-Environment="BROWSER_IDLE_REAPER_INTERVAL=30"-Environment="BROWSER_ORPHAN_PROFILE_MAX_AGE=43200"-Environment="BROWSER_FILE_UPLOAD_ALLOWED_DIRS=/srv/stealth-browser/uploads:/srv/stealth-browser/shared"-ExecStart=/path/to/venv/bin/python /path/to/stealth-browser-mcp/src/server.py --transport http --host 0.0.0.0-```--- **Docker / container HTTP**-```bash-docker run --rm -p 8000:8000 \- -e STEALTH_BROWSER_MCP_AUTH_TOKEN="replace-with-a-long-random-token" \- stealth-browser-mcp-```+**HTTP client example:**```pythonfrom fastmcp import Clientfrom fastmcp.client.auth import BearerAuthclient = Client(- "http://localhost:8000/mcp/",+ "http://127.0.0.1:8000/mcp/",auth=BearerAuth("replace-with-a-long-random-token"),)```-**Per-instance override**+**Per-instance idle override:**-If you want a single browser instance to live longer or shorter than the server default, pass `idle_timeout_seconds` in `spawn_browser(...)`.--Examples:- `spawn_browser(idle_timeout_seconds=1800)` keeps that instance for 30 minutes of inactivity.- `spawn_browser(idle_timeout_seconds=0)` disables idle reaping for that one instance.-**Available sections:**--| Section | Tools | Description |-|---------|-------|-------------|-| `browser-management` | 8 | Core browser operations |-| `element-interaction` | 12 | Page interaction and manipulation |-| `element-extraction` | 9 | Element cloning and extraction |-| `file-extraction` | 9 | File-based extraction tools |-| `network-debugging` | 10 | Network monitoring and interception |-| `cdp-functions` | 14 | Chrome DevTools Protocol execution |-| `progressive-cloning` | 10 | Advanced element cloning |-| `cookies-storage` | 3 | Cookie and storage management |-| `tabs` | 5 | Tab management |-| `debugging` | 7 | Debug and system tools |-| `dynamic-hooks` | 10 | AI-powered network hooks |----## Toolbox<details>-<summary><strong>Browser Management</strong></summary>+<summary><strong>Browser Management (8)</strong></summary>| Tool | Description ||------|-------------|-| `spawn_browser()` | Create undetectable browser instance |-| `navigate()` | Navigate to URLs |-| `close_instance()` | Clean shutdown of browser |-| `list_instances()` | Manage multiple sessions |+| `spawn_browser()` | Create a stealth browser instance |+| `list_instances()` | List active browser sessions |+| `close_instance()` | Clean shutdown of a browser || `get_instance_state()` | Full browser state information |+| `navigate()` | Navigate to URLs || `go_back()` | Navigate back in history || `go_forward()` | Navigate forward in history || `reload_page()` | Reload current page |+</details><details>-<summary><strong>Element Interaction</strong></summary>+<summary><strong>Element Interaction (12)</strong></summary>| Tool | Description ||------|-------------|-| `query_elements()` | Find elements by CSS/XPath |-| `click_element()` | Natural clicking |+| `query_elements()` | Find elements by CSS selector or XPath |+| `click_element()` | Click an element || `type_text()` | Human-like typing with newline support |-| `paste_text()` | Instant text pasting via CDP |+| `paste_text()` | Instant text paste via CDP || `file_upload()` | Upload allowlisted local files to file inputs |-| `scroll_page()` | Natural scrolling |-| `wait_for_element()` | Smart waiting |-| `execute_script()` | Run JavaScript |-| `select_option()` | Dropdown selection |-| `get_element_state()` | Element properties |-| `get_page_content()` | Full page HTML and text |-| `take_screenshot()` | Optimized page screenshots |+| `select_option()` | Select dropdown options |+| `get_element_state()` | Inspect element state |+| `wait_for_element()` | Wait for an element |+| `scroll_page()` | Scroll naturally |+| `execute_script()` | Run page JavaScript |+| `get_page_content()` | Read page HTML and text |+| `take_screenshot()` | Capture screenshots |</details><details>-<summary><strong>Element Extraction (CDP-accurate)</strong></summary>+<summary><strong>Network Debugging (10)</strong></summary>| 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 |+| `list_network_requests()` | List captured network requests |+| `get_request_details()` | Inspect request headers and payload |+| `get_response_details()` | Inspect response metadata |+| `get_response_content()` | Read captured response content |+| `search_network_requests()` | Search captured requests |+| `export_network_data()` | Export captured network data |+| `import_network_data()` | Import captured network data |+| `set_network_capture_filters()` | Configure capture filters |+| `get_network_capture_filters()` | Read active capture filters |+| `modify_headers()` | Add or replace request headers |</details><details>-<summary><strong>File-Based Extraction</strong></summary>+<summary><strong>Cookies and Storage (3)</strong></summary>| 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 |+| `get_cookies()` | Read cookies |+| `set_cookie()` | Set cookies |+| `clear_cookies()` | Clear cookies |</details><details>-<summary><strong>Network Debugging and Interception</strong></summary>+<summary><strong>Debugging (7)</strong></summary>| Tool | Description ||------|-------------|-| `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 |+| `get_debug_view()` | Debug logs and statistics with pagination |+| `clear_debug_view()` | Clear debug logs |+| `export_debug_logs()` | Export logs as JSON, pickle, or gzip |+| `get_debug_lock_status()` | Inspect debug logger lock state |+| `hot_reload()` | Reload modules without server restart |+| `reload_status()` | Check module reload status |+| `validate_browser_environment_tool()` | Diagnose browser/platform compatibility |</details><details>-<summary><strong>CDP Function Execution</strong></summary>+<summary><strong>Tabs (5)</strong></summary>| Tool | Description ||------|-------------|-| `execute_cdp_command()` | Direct CDP commands (use snake_case) |-| `add_script_to_evaluate_on_new_document()` | Install pre-document scripts for API spoofing |-| `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 |+| `list_tabs()` | List open tabs |+| `switch_tab()` | Change active tab |+| `close_tab()` | Close a tab |+| `get_active_tab()` | Get current active tab |+| `new_tab()` | Create a new tab |</details><details>-<summary><strong>Progressive Element Cloning</strong></summary>+<summary><strong>Element Extraction (9)</strong></summary>| 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 |+| `extract_element_styles()` | Extract computed CSS properties |+| `extract_element_structure()` | Extract DOM structure |+| `extract_element_events()` | Extract event listeners |+| `extract_element_animations()` | Extract animations and transitions |+| `extract_element_assets()` | Extract images, fonts, videos, and assets |+| `extract_element_styles_cdp()` | Pure CDP style extraction |+| `extract_related_files()` | Find related CSS/JS files |+| `clone_element_complete()` | Complete element cloning |+| `extract_complete_element_cdp()` | Complete CDP-based element clone |++</details>++<details>+<summary><strong>Progressive Cloning (10)</strong></summary>++| Tool | Description |+|------|-------------|+| `clone_element_progressive()` | Initial lightweight element clone |+| `expand_styles()` | Expand styles on demand |+| `expand_events()` | Expand events on demand |+| `expand_children()` | Expand child nodes on demand |+| `expand_css_rules()` | Expand CSS rule data || `expand_pseudo_elements()` | Expand pseudo-elements |-| `expand_animations()` | Expand animations data |-| `list_stored_elements()` | List stored elements |-| `clear_stored_element()` | Clear specific element |+| `expand_animations()` | Expand animation data |+| `list_stored_elements()` | List stored progressive clones |+| `clear_stored_element()` | Clear one stored element || `clear_all_elements()` | Clear all stored elements |</details><details>-<summary><strong>Cookie and Storage</strong></summary>+<summary><strong>File-Based Extraction (9)</strong></summary>| Tool | Description ||------|-------------|-| `get_cookies()` | Read cookies |-| `set_cookie()` | Set cookies |-| `clear_cookies()` | Clear cookies |-| `get_instance_state()` | localStorage and sessionStorage snapshot |-| `execute_script()` | Read/modify storage via JS |+| `clone_element_to_file()` | Save complete clone to file |+| `extract_complete_element_to_file()` | Save complete extraction to file |+| `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 |+| `list_clone_files()` | List saved clone files |+| `cleanup_clone_files()` | Clean up old clone files |</details><details>-<summary><strong>Tabs</strong></summary>+<summary><strong>CDP Function Execution (14)</strong></summary>| 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 |+| `list_cdp_commands()` | List available CDP commands |+| `execute_cdp_command()` | Run direct CDP commands |+| `add_script_to_evaluate_on_new_document()` | Install scripts before page JavaScript runs |+| `get_execution_contexts()` | List JavaScript execution contexts |+| `discover_global_functions()` | Find global JavaScript functions |+| `discover_object_methods()` | Discover methods on JavaScript objects |+| `call_javascript_function()` | Execute a discovered JavaScript function |+| `inspect_function_signature()` | Inspect function details |+| `inject_and_execute_script()` | Inject and run custom JavaScript |+| `create_persistent_function()` | Create functions that survive reloads |+| `execute_function_sequence()` | Execute ordered function calls |+| `create_python_binding()` | Create Python-to-JS bindings |+| `execute_python_in_browser()` | Translate Python to JavaScript with py2js and run it |+| `get_function_executor_info()` | Inspect executor state |</details><details>-<summary><strong>Page Analysis and Debugging</strong></summary>+<summary><strong>Dynamic Hooks (10)</strong></summary>| 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 |-| `hot_reload()` | Reload modules without restart |-| `reload_status()` | Check module reload status |-| `validate_browser_environment_tool()` | Diagnose platform issues and browser compatibility |+| `create_dynamic_hook()` | Create a restricted Python network hook |+| `create_simple_dynamic_hook()` | Create hooks from common presets |+| `list_dynamic_hooks()` | List active hooks |+| `get_dynamic_hook_details()` | Inspect hook source and metadata |+| `remove_dynamic_hook()` | Remove a hook |+| `get_hook_documentation()` | Read request object and action docs |+| `get_hook_examples()` | View hook examples |+| `get_hook_requirements_documentation()` | Read matching and best-practice docs |+| `get_hook_common_patterns()` | Common hook patterns |+| `validate_hook_function()` | Validate hook code before use |</details>@@ -489,19 +515,19 @@ Examples:## Stealth vs Playwright MCP+Detection results are point-in-time and depend on site policy, region, browser version, IP reputation, and detector version. See [STEALTH_TESTS.md](STEALTH_TESTS.md) for the current manual snapshot and [issue #25](https://github.com/vibheksoni/stealth-browser-mcp/issues/25) for the proposed reproducible benchmark harness.+| 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 |+| Cloudflare / Queue-It style checks | Passes common JS challenges in testing | Commonly blocked |+| Hardened sites | Uses real Chrome-family browser instances through nodriver | Frequently flagged as automation |+| Login-walled pages | Can inspect loaded content and overlays through CDP | Often requires manual scripting || UI element cloning | CDP-accurate extraction | Limited |-| Network debugging | Full request/response inspection via AI | Basic |+| Network debugging | Full request/response inspection through AI tools | 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, 20–97 tools | Fixed ~20 tools |-| Total tools | 97 (customizable) | ~20 |--Tested on: LinkedIn, Instagram, Twitter/X, Amazon, banking portals, government sites, Cloudflare-protected APIs, Nike SNKRS, Ticketmaster, Supreme.+| Dynamic hook system | Restricted Python hooks for real-time interception | Not available |+| Modular architecture | 11 sections, 20-97 tools | Fixed tool surface |+| Total tools | 97 customizable tools | About 20 |---@@ -511,25 +537,27 @@ Tested on: LinkedIn, Instagram, Twitter/X, Amazon, banking portals, government sInstall Chrome, Chromium, or Microsoft Edge. The server auto-detects the first available browser. Run `validate_browser_environment_tool()` to diagnose.**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.+Debug output must not print to stdout during MCP `stdio` transport. Pull the latest `master` branch and keep debug logging disabled unless diagnosing a problem.**Need verbose diagnostics without noisy normal runs**Use `python src/server.py --debug` or set `STEALTH_BROWSER_DEBUG=1`. Debug logs are emitted to `stderr`; normal MCP `stdio` runs stay quiet by default.-**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.+**Browser crashes on Linux, Docker, or CI**+Run with `--sandbox=false` only if your environment requires it, or ensure the environment supports Chromium sandboxing. The server auto-detects root/container environments and adjusts launch arguments.-**Orphan Chromium processes or `uc_*` temp profiles accumulate on long-running hosts**-The server now reaps idle browser instances automatically and performs startup cleanup of tracked orphan browser processes plus stale `uc_*` temp profiles. Set `BROWSER_IDLE_TIMEOUT=0` to disable idle reaping if you want fully manual browser lifetime management.+**Orphan Chromium processes or `uc_*` temp profiles accumulate**+The server reaps idle browser instances automatically and performs startup cleanup of tracked orphan browser processes plus stale `uc_*` temp profiles. Set `BROWSER_IDLE_TIMEOUT=0` only if you want fully manual browser lifetime management.**Too many tools cluttering the AI chat**-Use `--minimal` for 20 core tools, or selectively disable sections:+Use `--minimal` for 20 core tools, `--xpool-safe` for xpool-compatible operation, or selectively disable sections:+```bashpython src/server.py --disable-cdp-functions --disable-dynamic-hooks --disable-progressive-cloning```**Module not found errors**Make sure you activated the virtual environment and installed dependencies:+```bashpip install -r requirements.txt```@@ -538,10 +566,11 @@ pip install -r requirements.txt## Examples-- **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+- **Market research** - Extract pricing and features from competitors, then output a comparison table.+- **UI cloning** - Recreate a pricing section with exact fonts, styles, assets, and interactions.+- **Inventory monitoring** - Watch a product page and alert when stock changes.+- **API reverse engineering** - Intercept requests, map endpoints, and inspect data flow.+- **Form automation** - Upload files from allowlisted paths and verify resulting page state.All driven from a single AI agent conversation.@@ -553,7 +582,7 @@ All driven from a single AI agent conversation.<img src="media/AugmentHeroClone.PNG" alt="Augment Code Hero Recreation" width="700" style="border-radius: 8px;"></div>-**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.+**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.[View the recreation](demo/augment-hero-recreation.html) | [Full walkthrough](demo/augment-hero-clone.md)@@ -569,7 +598,7 @@ See the live plan in [ROADMAP.md](ROADMAP.md). Contributions welcome.Read [CONTRIBUTING.md](CONTRIBUTING.md) and open a PR. First-time contributors welcome.-If this project saves you time, star the repo — it helps more than you think.+If this project saves you time, star the repo. It helps more than you think.---@@ -578,18 +607,9 @@ If this project saves you time, star the repo — it helps more than you think.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-MIT — see [LICENSE](LICENSE).-------<div align="center">--[](https://www.star-history.com/#vibheksoni/stealth-browser-mcp&Date)--</div>+MIT - see [LICENSE](LICENSE).diff --git a/media/UndetectedStealthBrowser-2.png b/media/UndetectedStealthBrowser-2.pngnew file mode 100644index 0000000..bb7fb28Binary files /dev/null and b/media/UndetectedStealthBrowser-2.png differdiff --git a/media/nodemaven-sponsor.png b/media/nodemaven-sponsor.pngnew file mode 100644index 0000000..e1b5803Binary files /dev/null and b/media/nodemaven-sponsor.png differ