<div align="center"> <img src="media/UndetectedStealthBrowser-2.png" alt="Stealth Browser MCP logo" width="200"/>

Stealth Browser MCP

Stealth browser automation for MCP-compatible AI agents.

Navigate Cloudflare challenges, anti-bot checks, and login walls with real Chrome-family browser instances powered by nodriver, Chrome DevTools Protocol, and FastMCP.

</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 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 — 40% off ISP Static Proxies

Get started with NodeMaven

</td> </tr> </table>

Sponsored placement. NodeMaven is a paid sponsor of this project.

---

Table of Contents

• Sponsored by NodeMaven
• Demo
• Features
• Quickstart
• Agent Skill
• Trust Model
• Modular Architecture
• Server Configuration
• Toolbox
• Stealth vs Playwright MCP
• Troubleshooting
• Examples
• Showcase
• Roadmap
• Contributing
• Support
• License

---

Demo

<div align="center"> <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 passing a Cloudflare challenge, cloning UI elements, and inspecting network traffic through AI chat commands.

---

Features

• 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.

---

Quickstart

1. Clone and install

Requires Python 3.10+ and Chrome, Chromium, or Microsoft Edge.

git clone https://github.com/vibheksoni/stealth-browser-mcp.git
cd stealth-browser-mcp
python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

2. Add to your MCP client

Claude Code CLI (recommended):

Windows:

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\"]}"

macOS / Linux:

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"]
}'

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

{
  "mcpServers": {
    "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": {}
    }
  }
}

macOS / Linux (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stealth-browser-mcp": {
      "command": "/path/to/stealth-browser-mcp/venv/bin/python",
      "args": ["/path/to/stealth-browser-mcp/src/server.py"],
      "env": {}
    }
  }
}

</details> <details> <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.

pip install fastmcp
fastmcp install claude-desktop src/server.py --with-requirements requirements.txt
fastmcp install claude-code src/server.py --with-requirements requirements.txt
fastmcp install cursor src/server.py --with-requirements requirements.txt

</details>

3. Test it

Restart your MCP client and ask your agent:

Use stealth-browser to navigate to https://example.com and take a screenshot.

---

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.

Use the skill when an LLM struggles to choose the right MCP tool or forgets to verify browser state after actions. If your client does not load repo-local skills automatically, add or symlink skills/stealth-browser-mcp into your client skills directory.

---

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 the 20-tool core.

| Mode | Tools | Use Case | |------|-------|----------| | Full (default) | 97 | Complete browser automation and debugging | | 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 |

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. Normal MCP stdio runs stay quiet by default to avoid corrupting JSON-RPC transport output.

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 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 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 | |----------|---------|---------| | STEALTH_BROWSER_MCP_AUTH_TOKEN | unset | Optional bearer token for HTTP transport. When set, HTTP clients must send Authorization: Bearer <token>. | | 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. 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. |

PowerShell example:

$env:STEALTH_BROWSER_MCP_AUTH_TOKEN='replace-with-a-long-random-token'
$env:BROWSER_IDLE_TIMEOUT='900'
$env:BROWSER_IDLE_REAPER_INTERVAL='30'
$env:BROWSER_ORPHAN_PROFILE_MAX_AGE='43200'
$env:BROWSER_FILE_UPLOAD_ALLOWED_DIRS='C:\Users\me\uploads;C:\Users\me\Documents'
python src/server.py

MCP client env block:

{
  "mcpServers": {
    "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_MCP_AUTH_TOKEN": "replace-with-a-long-random-token",
        "BROWSER_IDLE_TIMEOUT": "900",
        "BROWSER_FILE_UPLOAD_ALLOWED_DIRS": "C:\\Users\\me\\uploads;C:\\Users\\me\\Documents"
      }
    }
  }
}

HTTP client example:

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

client = Client(
    "http://127.0.0.1:8000/mcp/",
    auth=BearerAuth("replace-with-a-long-random-token"),
)

Per-instance idle override:

• spawn_browser(idle_timeout_seconds=1800) keeps that instance for 30 minutes of inactivity.
• spawn_browser(idle_timeout_seconds=0) disables idle reapi