vibheksoni/stealth-browser-mcp

---

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

---

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.

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.

---

Modular Architecture

Choose exactly what functionality you need. Run the full 97-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 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.

---