shelfry.app/p/stealth-browser-mcp

stealth-browser-mcp

Stealth Browser MCP 是一个基于 Model Context Protocol 的浏览器自动化服务端，让 Claude、Cursor 等支持 MCP 的客户端通过自然语言指令操控本机的 Chrome、Chromium 或 Edge 实例。它基于 nodriver 和 Chrome DevTools 协议运行真实浏览器，在测试中可通过 Cloudflare 一类的人机校验，降低被识别为自动化脚本的概率。功能涵盖页面导航、元素点击与输入、完整 DOM 与样式克隆、网络请求查看与拦截改写、Cookie 管理、标签页控制等。工具按 11 个分区组织，默认提供 101 个工具，也可只加载 21 个核心工具以减少上下文开销。仓库另附一份 Agent 技能文档，说明推荐的调用顺序与浏览器清理规则。

WebMCP Server MIT

GitHub

$git clone https://github.com/vibheksoni/stealth-browser-mcp.git && cd stealth-browser-mcp && pip install -e .

Stars

3.1K

Forks

409

语言

Python

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.

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.

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

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

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

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

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.

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.

Mode	Tools	Use Case
Full (default)	101	Complete browser automation and debugging
Minimal (`--minimal`)	21	Core browser automation and interaction
Custom (`--disable-*`)	Your choice	Disable specific sections
Xpool safe (`--xpool-safe`)	84	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.

Section	Tools	Description
`browser-management`	8	Core browser operations
`element-interaction`	13	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`	17	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

Variable	Default	Meaning
`STEALTH_BROWSER_MCP_AUTH_TOKEN`	unset	Optional bearer token for HTTP transport. When set, HTTP clients must send `Authorization: Bearer` .
`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_TAB_RECYCLE_NAVIGATIONS`	`0`	Replace the main tab with a fresh one after this many navigations. `0` keeps the same tab, which preserves history and session storage.
`BROWSER_ORPHAN_PROFILE_MAX_AGE`	`21600`	Startup cleanup threshold in seconds for stale `uc_*` temp profiles. Set `0` to disable this startup sweep.
`STEALTH_BROWSER_EXECUTABLE`	auto-detect	Path to the Chrome, Chromium, or Edge executable to launch instead of the auto-detected one.
`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.

$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

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

Tool	Description
`spawn_browser()`	Create a stealth browser instance
`list_instances()`	List active browser sessions
`close_instance()`	Clean shutdown of a browser
`get_instance_state()`	Full browser state information
`navigate()`	Navigate to URLs
`go_back()`	Navigate back in history
`go_forward()`	Navigate forward in history
`reload_page()`	Reload current page

Tool	Description
`query_elements()`	Find elements by CSS selector or XPath
`click_element()`	Click an element
`type_text()`	Human-like typing with newline support
`paste_text()`	Instant text paste via CDP
`press_key()`	Press a real key with trusted CDP key events (Enter, Tab, arrows, modifiers)
`file_upload()`	Upload allowlisted local files to file inputs
`select_option()`	Select dropdown options
`get_element_state()`	Inspect element state
`wait_for_element()`	Wait for an element
`scroll_page()`	Scroll naturally
`execute_script()`	Run page JavaScript
`get_page_content()`	Read page HTML and text
`take_screenshot()`	Capture screenshots

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.

Tool	Description
`list_network_requests()`	List captured network requests
`get_request_details()`	Inspect request headers and payload
`get_response_details()`	Inspect response metadata
`get_response_content()`	Read captured response content
`search_network_requests()`	Search captured requests
`export_network_data()`	Export captured network data
`import_network_data()`	Import captured network data
`set_network_capture_filters()`	Configure capture filters
`get_network_capture_filters()`	Read active capture filters
`modify_headers()`	Add or replace request headers

Tool	Description
`get_cookies()`	Read cookies
`set_cookie()`	Set cookies
`clear_cookies()`	Clear cookies

Tool	Description
`get_debug_view()`	Debug logs and statistics with pagination
`clear_debug_view()`	Clear debug logs
`export_debug_logs()`	Export logs as JSON, pickle, or gzip
`get_debug_lock_status()`	Inspect debug logger lock state
`hot_reload()`	Reload modules without server restart
`reload_status()`	Check module reload status
`validate_browser_environment_tool()`	Diagnose browser/platform compatibility

Tool	Description
`list_tabs()`	List open tabs
`switch_tab()`	Change active tab
`close_tab()`	Close a tab
`get_active_tab()`	Get current active tab
`new_tab()`	Create a new tab

Tool	Description
`extract_element_styles()`	Extract computed CSS properties
`extract_element_structure()`	Extract DOM structure
`extract_element_events()`	Extract event listeners
`extract_element_animations()`	Extract animations and transitions
`extract_element_assets()`	Extract images, fonts, videos, and assets
`extract_element_styles_cdp()`	Pure CDP style extraction
`extract_related_files()`	Find related CSS/JS files
`clone_element_complete()`	Complete element cloning
`extract_complete_element_cdp()`	Complete CDP-based element clone

Tool	Description
`clone_element_progressive()`	Initial lightweight element clone
`expand_styles()`	Expand styles on demand
`expand_events()`	Expand events on demand
`expand_children()`	Expand child nodes on demand
`expand_css_rules()`	Expand CSS rule data
`expand_pseudo_elements()`	Expand pseudo-elements
`expand_animations()`	Expand animation data
`list_stored_elements()`	List stored progressive clones
`clear_stored_element()`	Clear one stored element
`clear_all_elements()`	Clear all stored elements

Tool	Description
`clone_element_to_file()`	Save complete clone to file
`extract_complete_element_to_file()`	Save complete extraction to file
`extract_element_styles_to_file()`	Save styles to file
`extract_element_structure_to_file()`	Save structure to file
`extract_element_events_to_file()`	Save events to file
`extract_element_animations_to_file()`	Save animations to file
`extract_element_assets_to_file()`	Save assets to file
`list_clone_files()`	List saved clone files
`cleanup_clone_files()`	Clean up old clone files

Tool	Description
`list_cdp_commands()`	List available CDP commands
`execute_cdp_command()`	Run direct CDP commands
`add_script_to_evaluate_on_new_document()`	Install scripts before page JavaScript runs
`get_execution_contexts()`	List JavaScript execution contexts
`discover_global_functions()`	Find global JavaScript functions
`discover_object_methods()`	Discover methods on JavaScript objects
`call_javascript_function()`	Execute a discovered JavaScript function
`inspect_function_signature()`	Inspect function details
`inject_and_execute_script()`	Inject and run custom JavaScript
`create_persistent_function()`	Create functions that survive reloads
`create_page_binding()`	Expose `window.()` so page JavaScript can call back to the agent
`get_page_binding_calls()`	Read queued page binding calls, optionally waiting for one
`resolve_page_binding_call()`	Answer a page binding call with a value or an error
`remove_page_binding()`	Remove a page binding and reject its pending calls
`execute_function_sequence()`	Execute ordered function calls
`execute_python_in_browser()`	Translate Python to JavaScript with py2js and run it
`get_function_executor_info()`	Inspect executor state

Tool	Description
`create_dynamic_hook()`	Create a restricted Python network hook
`create_simple_dynamic_hook()`	Create hooks from common presets
`list_dynamic_hooks()`	List active hooks
`get_dynamic_hook_details()`	Inspect hook source and metadata
`remove_dynamic_hook()`	Remove a hook
`get_hook_documentation()`	Read request object and action docs
`get_hook_examples()`	View hook examples
`get_hook_requirements_documentation()`	Read matching and best-practice docs
`get_hook_common_patterns()`	Common hook patterns
`validate_hook_function()`	Validate hook code before use

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.

Feature	Stealth Browser MCP	Playwright MCP
Cloudflare / Queue-It style checks	Passes common JS challenges in testing	Commonly blocked
Hardened sites	Uses real Chrome-family browser instances through nodriver	Frequently flagged as automation
Login-walled pages	Can inspect loaded content and overlays through CDP	Often requires manual scripting
UI element cloning	CDP-accurate extraction	Limited
Network debugging	Full request/response inspection through AI tools	Basic
API reverse engineering	Payload inspection through chat	Manual tools only
Dynamic hook system	Restricted Python hooks for real-time interception	Not available
Modular architecture	11 sections, 21-101 tools	Fixed tool surface
Total tools	101 customizable tools	About 20

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:

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.

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.

stealth-browser-mcp

Stealth Browser MCP

Sponsors

Table of Contents

Demo

Features

Quickstart

1. Clone and install

2. Add to your MCP client

3. Test it

Agent Skill

Trust Model

Modular Architecture

Server Configuration

Toolbox

Stealth vs Playwright MCP

Troubleshooting

Examples

Showcase

Roadmap

Contributing

Support

License

核心功能