vibheksoni/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 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.
2. Add to your MCP client
**Claude Code CLI (recommended):**
Windows:
macOS / Linux:
Replace the example path with your real clone path.
Manual JSON configuration (Claude Desktop, Cursor, etc.)
Windows (%APPDATA%\Claude\claude_desktop_config.json):
macOS / Linux (~/Library/Application Support/Claude/claude_desktop_config.json):
Experimental FastMCP CLI install
These commands are provided for users who prefer FastMCP's installer. The stdio JSON setup above is the recommended 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.
---
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.
| Mode | Tools | Use Case |
|------|-------|----------|
| **Full** (default) | 101 | Complete browser automation and debugging |