Stealth Browser MCP

Undetectable browser automation for MCP-compatible AI agents.

Bypass Cloudflare, antibot systems, and social media blocks with real browser instances powered by nodriver + Chrome DevTools Protocol + FastMCP.

Table of Contents

• Demo
• Features
• Quickstart
• Modular Architecture
• Toolbox
• Stealth vs Playwright MCP
• Troubleshooting
• Examples
• Showcase
• Roadmap
• Contributing
• Support
• License

Demo

Stealth Browser MCP bypassing Cloudflare, cloning UI elements, and intercepting network traffic — all through AI chat commands.

Features

• Antibot bypass — Works on Cloudflare, Queue-It, and other protection systems that block traditional automation
• 96 tools across 11 sections — From basic navigation to advanced CDP function execution
• Modular loading — Run the full 96-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

Quickstart

1. Clone and install

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

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Mac/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\"]}"

Mac/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 /path/to/stealth-browser-mcp/ with your actual project path.

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

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

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

3. Test it

Restart your MCP client and ask your agent:

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

Modular Architecture

Choose exactly what functionality you need. Run the full 96-tool suite or strip it down to 20 core tools.

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

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.

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.

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.

Server Environment Variables

These are regular environment variables for the MCP server process itself. Set them wherever you launch src/server.py:

Where to set them

• Shell / local terminal

# 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

# 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'
$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 config Put them in the server env block for your client.

{
  "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_IDLE_REAPER_INTERVAL": "30",
        "BROWSER_ORPHAN_PROFILE_MAX_AGE": "43200",
        "BROWSER_FILE_UPLOAD_ALLOWED_DIRS": "C:\\Users\\me\\uploads;C:\\Users\\me\\Documents"
      }
    }
  }
}

• systemd / long-running service

[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

docker run --rm -p 8000:8000 \
  -e STEALTH_BROWSER_MCP_AUTH_TOKEN="replace-with-a-long-random-token" \
  stealth-browser-mcp

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

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

Per-instance 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:

Toolbox

Stealth vs Playwright MCP

Tested on: LinkedIn, Instagram, Twitter/X, Amazon, banking portals, government sites, Cloudflare-protected APIs, Nike SNKRS, Ticketmaster, Supreme.

Troubleshooting

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.

Tools hang or return malformed JSON Debug output was printing to stdout, corrupting the MCP JSON-RPC protocol. This was fixed in #8. Pull the latest master branch.

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.

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.

Too many tools cluttering the AI chat Use --minimal for 20 core tools, or selectively disable sections:

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:

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

All driven from a single AI agent conversation.

Showcase

Augment Code hero clone — A user asked Claude to clone the hero section from 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 | Full walkthrough

Roadmap

See the live plan in ROADMAP.md. Contributions welcome.

Contributing

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

Support

If this tool saved you time or made you money, consider supporting development:

• Buy me a coffee
• Join the Discord

License

MIT — see LICENSE.