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.

Refresh README: new logo, NodeMaven sponsorship, corrected tool docs, tightened claims

Vibhek Soni8d234b4d6367
diff --git a/.gitignore b/.gitignore
index 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 file
diff --git a/README.md b/README.md
index 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).
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
+[![Version](https://img.shields.io/badge/version-0.2.5-blue?style=flat-square)](pyproject.toml)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square)](pyproject.toml)
[![Stars](https://img.shields.io/github/stars/vibheksoni/stealth-browser-mcp?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/stargazers)
[![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>
---
+## 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.
+
```bash
git clone https://github.com/vibheksoni/stealth-browser-mcp.git
cd stealth-browser-mcp
python -m venv venv
-# Activate virtual environment
-# Windows:
+# Windows
venv\Scripts\activate
-# Mac/Linux:
+
+# macOS / Linux
source venv/bin/activate
pip install -r requirements.txt
@@ -88,11 +132,13 @@ pip install -r requirements.txt
**Claude Code CLI (recommended):**
Windows:
-```bash
+
+```powershell
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:
+macOS / Linux:
+
```bash
claude 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.
```bash
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
```
@@ -152,9 +200,11 @@ fastmcp install cursor src/server.py --with-requirements requirements.txt
Restart 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 Skill
This 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` |
```bash
python src/server.py --minimal
python src/server.py --disable-cdp-functions --disable-dynamic-hooks
python src/server.py --list-sections
python 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\Documents
python 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:**
```python
from fastmcp import Client
from fastmcp.client.auth import BearerAuth
client = 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 s
Install 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:
+
```bash
python 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:
+
```bash
pip 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">
-
-[![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>
+MIT - see [LICENSE](LICENSE).
diff --git a/media/UndetectedStealthBrowser-2.png b/media/UndetectedStealthBrowser-2.png
new file mode 100644
index 0000000..bb7fb28
Binary files /dev/null and b/media/UndetectedStealthBrowser-2.png differ
diff --git a/media/nodemaven-sponsor.png b/media/nodemaven-sponsor.png
new file mode 100644
index 0000000..e1b5803
Binary files /dev/null and b/media/nodemaven-sponsor.png differ