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.
Sponsors
NodeMaven — The most efficient proxy provider for Web Scraping and Automation with the Highest Quality IP on the market.
Why NodeMaven?
- ZIP targeting
- 99.9% uptime
- IP filtering: all proxies have fraud score <97%
- No KYC required
- Unique free tools: Proxy Bandwidth Checker, Meta Tag Checker, IP Lookup and others!
Special codes for Stealth-browser-mcp users
STEALTHMCP35— 35% off to Mobile and Residential ProxiesSTEALTHMCP40— 40% off to ISP (Static) Proxies
Sponsored placement. NodeMaven is a paid sponsor of this project.
Table of Contents
- Sponsors
- Demo
- Features
- Quickstart
- Agent Skill
- Trust Model
- Modular Architecture
- Server Configuration
- Toolbox
- Stealth vs Playwright MCP
- Troubleshooting
- Examples
- Showcase
- Roadmap
- Contributing
- Support
- License
Demo
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.
- 101 tools across 11 sections - From basic navigation to advanced CDP function execution.
- Modular loading - Run the full 101-tool surface or a minimal 21-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, type with human-like keystrokes, or press real keys with trusted CDP key events.
- 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.
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": {}
}
}
}
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
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 101-tool suite or strip it down to the 21-tool core.
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:
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.
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 reaping for that one instance.
Toolbox
take_screenshot returns an MCP image with metadata (format, size, scale, quality, byte count, SHA-256), so remote clients can show it without reading the server's disk. Large captures, such as long full-page screenshots, are scaled down to fit client limits (8000 px per side, about 5 MB), and the metadata reports the original size. Pass format="jpeg" with a lower quality, or max_width, for smaller images, or file_path to save the full-resolution image on the server.
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 for weekly automated results from the benchmark in benchmarks/stealth/, which runs on Linux, Windows, and macOS in GitHub Actions, plus the earlier manual snapshot.
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 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, 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
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, --xpool-safe for xpool-compatible operation, 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, 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.
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:
License
MIT - see LICENSE.