Skip to content
Back to search

stealth-browser-mcp

The only browser automation that bypasses anti-bot systems. AI writes network hooks, clones UIs pixel-perfect via simple chat.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/vibheksoni/stealth-browser-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/vibheksoni/stealth-browser-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vibheksoni--stealth-browser-mcp/badge.svg)](/listings/vibheksoni--stealth-browser-mcp)

HTML

<a href="/listings/vibheksoni--stealth-browser-mcp"><img src="/api/listings/vibheksoni--stealth-browser-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

<details> <summary><strong>Manual JSON configuration (Claude Desktop, Cursor, etc.)</strong></summary>

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

</details>

<details> <summary><strong>Experimental FastMCP CLI install</strong></summary>

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

</details>

3. Test it

Restart your MCP client and ask your agent:

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 653 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/vibheksoni/stealth-browser-mcp/master/media/UndetectedStealthBrowser-2.png" alt="Stealth Browser MCP logo" width="200"/>
  3. # Stealth Browser MCP
  4. **Stealth browser automation for MCP-compatible AI agents.**
  5. Navigate Cloudflare challenges, anti-bot checks, and login walls with real Chrome-family browser instances powered by [nodriver](https://github.com/ultrafunkamsterdam/nodriver), Chrome DevTools Protocol, and [FastMCP](https://github.com/jlowin/fastmcp).
  6. [![MCP](https://img.shields.io/badge/MCP-Compatible-blue?style=flat-square)](https://modelcontextprotocol.io)
  7. [![PyPI](https://img.shields.io/pypi/v/browserstealthmcp?style=flat-square)](https://pypi.org/project/browserstealthmcp/)
  8. [![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/pyproject.toml)
  9. [![Stars](https://img.shields.io/github/stars/vibheksoni/stealth-browser-mcp?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/stargazers)
  10. [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/LICENSE)
  11. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/CONTRIBUTING.md)
  12. </div>
  13. ---
  14. ## Sponsors
  15. <a href="https://go.nodemaven.com/stealthbrowsermcpreadmeoct"><img src="https://raw.githubusercontent.com/vibheksoni/stealth-browser-mcp/master/media/nodemaven-sponsor.png" alt="NodeMaven" width="100%"></a>
  16. [NodeMaven](https://go.nodemaven.com/stealthbrowsermcpreadmeoct) — The most efficient proxy provider for Web Scraping and Automation with the Highest Quality IP on the market.
  17. **Why NodeMaven?**
  18. - ZIP targeting
  19. - 99.9% uptime
  20. - IP filtering: all proxies have fraud score <97%
  21. - No KYC required
  22. - Unique free tools: Proxy Bandwidth Checker, Meta Tag Checker, IP Lookup and others!
  23. **Special codes for Stealth-browser-mcp users**
  24. - `STEALTHMCP35` — 35% off to Mobile and Residential Proxies
  25. - `STEALTHMCP40` — 40% off to ISP (Static) Proxies
  26. - `STEALTHMCP2X`: 2X traffic for Black Friday
  27. [Get started with NodeMaven](https://go.nodemaven.com/stealthbrowsermcpreadmeoct)
  28. > Sponsored placement. NodeMaven is a paid sponsor of this project.
  29. ---
  30. ## Table of Contents
  31. - [Sponsors](#sponsors)
  32. - [Demo](#demo)
  33. - [Features](#features)
  34. - [Quickstart](#quickstart)
  35. - [Agent Skill](#agent-skill)
  36. - [Trust Model](#trust-model)
  37. - [Modular Architecture](#modular-architecture)
  38. - [Server Configuration](#server-configuration)
  39. - [Toolbox](#toolbox)
  40. - [Stealth vs Playwright MCP](#stealth-vs-playwright-mcp)
  41. - [Troubleshooting](#troubleshooting)
  42. - [Examples](#examples)
  43. - [Showcase](#showcase)
  44. - [Roadmap](#roadmap)
  45. - [Contributing](#contributing)
  46. - [Support](#support)
  47. - [License](#license)
  48. ---
  49. ## Demo
  50. <div align="center">
  51. <img src="https://raw.githubusercontent.com/vibheksoni/stealth-browser-mcp/master/media/showcase-demo-full.gif" alt="Stealth Browser MCP demo" width="800" style="border-radius: 8px;">
  52. <br><br>
  53. <a href="https://raw.githubusercontent.com/vibheksoni/stealth-browser-mcp/master/media/Showcase%20Stealth%20Browser%20Mcp.mp4" download>
  54. <img src="https://img.shields.io/badge/Watch%20HD%20Video-red?style=for-the-badge&logo=video&logoColor=white" alt="Watch HD Video">
  55. </a>
  56. </div>
  57. *Stealth Browser MCP passing a Cloudflare challenge, cloning UI elements, and inspecting network traffic through AI chat commands.*
  58. ---
  59. ## Features
  60. - **Anti-bot resistance** - Has passed Cloudflare and Queue-It style challenges in testing; results vary by site, region, browser version, and detector version.
  61. - **101 tools across 11 sections** - From basic navigation to advanced CDP function execution.
  62. - **Modular loading** - Run the full 101-tool surface or a minimal 21-tool core; disable sections you do not need.
  63. - **Pixel-accurate element cloning** - Extract complete elements with CSS, DOM structure, events, animations, and assets via CDP.
  64. - **Network inspection** - Inspect requests, responses, headers, payloads, and captured bodies through your AI agent.
  65. - **Dynamic hook system** - Restricted Python hooks can intercept, block, redirect, fulfill, or modify request/response flows.
  66. - **CDP execution** - Run JavaScript, direct CDP commands, and pre-document scripts through trusted local MCP clients.
  67. - **Instant text input** - Paste large content via CDP, type with human-like keystrokes, or press real keys with trusted CDP key events.
  68. - **Cross-platform** - Windows, macOS, Linux, Docker, and CI environments with automatic browser/platform detection.
  69. - **Browser support** - Chrome, Chromium, and Microsoft Edge with automatic executable discovery.
  70. - **Clean MCP integration** - Works through standard MCP clients without custom brokers.
  71. ---
  72. ## Quickstart
  73. ### 1. Install
  74. Requires Python 3.10+ and Chrome, Chromium, or Microsoft Edge.
  75. **With pipx (recommended):**
  76. ```bash
  77. pipx install browserstealthmcp
  78. ```
  79. This puts a `stealth-browser-mcp` command on your `PATH`. Upgrade with `pipx upgrade browserstealthmcp`. `uvx browserstealthmcp` runs it without installing. To run the latest commit instead of a release, use `pipx install git+https://github.com/vibheksoni/stealth-browser-mcp.git`.
  80. The PyPI package is named `browserstealthmcp` because `stealth-browser-mcp` on PyPI belongs to a different, unrelated project. `pipx install stealth-browser-mcp` installs that project, not this one.
  81. **From a clone (for development):**
  82. ```bash
  83. git clone https://github.com/vibheksoni/stealth-browser-mcp.git
  84. cd stealth-browser-mcp
  85. python -m venv venv
  86. # Windows
  87. venv\Scripts\activate
  88. # macOS / Linux
  89. source venv/bin/activate
  90. pip install -r requirements.txt
  91. ```
  92. ### 2. Add to your MCP client
  93. **Installed with pipx:**
  94. ```bash
  95. claude mcp add stealth-browser-mcp -- stealth-browser-mcp
  96. ```
  97. Or in any client's JSON config:
  98. ```json
  99. {
  100. "mcpServers": {
  101. "stealth-browser-mcp": {
  102. "command": "stealth-browser-mcp",
  103. "args": [],
  104. "env": {}
  105. }
  106. }
  107. }
  108. ```
  109. If your client cannot find the command, use the full path printed by `pipx list`. With uv you can skip the install and use `"command": "uvx", "args": ["browserstealthmcp"]`.
  110. **From a clone with Claude Code CLI:**
  111. Windows:
  112. ```powershell
  113. 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\"]}"
  114. ```
  115. macOS / Linux:
  116. ```bash
  117. claude mcp add-json stealth-browser-mcp '{
  118. "type": "stdio",
  119. "command": "/path/to/stealth-browser-mcp/venv/bin/python",
  120. "args": ["/path/to/stealth-browser-mcp/src/server.py"]
  121. }'
  122. ```
  123. Replace the example path with your real clone path.
  124. <details>
  125. <summary><strong>Manual JSON configuration (Claude Desktop, Cursor, etc.)</strong></summary>
  126. Windows (`%APPDATA%\Claude\claude_desktop_config.json`):
  127. ```json
  128. {
  129. "mcpServers": {
  130. "stealth-browser-mcp": {
  131. "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
  132. "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
  133. "env": {}
  134. }
  135. }
  136. }
  137. ```
  138. macOS / Linux (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  139. ```json
  140. {
  141. "mcpServers": {
  142. "stealth-browser-mcp": {
  143. "command": "/path/to/stealth-browser-mcp/venv/bin/python",
  144. "args": ["/path/to/stealth-browser-mcp/src/server.py"],
  145. "env": {}
  146. }
  147. }
  148. }
  149. ```
  150. </details>
  151. <details>
  152. <summary><strong>Experimental FastMCP CLI install</strong></summary>
  153. These commands are provided for users who prefer FastMCP's installer. The stdio JSON setup above is the recommended path.
  154. ```bash
  155. pip install fastmcp
  156. fastmcp install claude-desktop src/server.py --with-requirements requirements.txt
  157. fastmcp install claude-code src/server.py --with-requirements requirements.txt
  158. fastmcp install cursor src/server.py --with-requirements requirements.txt
  159. ```
  160. </details>
  161. ### 3. Test it
  162. Restart your MCP client and ask your agent:
  163. > Use stealth-browser to navigate to https://example.com and take a screenshot.
  164. ---
  165. ## Agent Skill
  166. 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.
  167. 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.
  168. ---
  169. ## Trust Model
  170. 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.
  171. 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.
  172. ---
  173. ## Modular Architecture
  174. Choose exactly what functionality you need. Run the full 101-tool suite or strip it down to the 21-tool core.
  175. | Mode | Tools | Use Case |
  176. |------|-------|----------|
  177. | **Full** (default) | 101 | Complete browser automation and debugging |
  178. | **Minimal** (`--minimal`) | 21 | Core browser automation and interaction |
  179. | **Custom** (`--disable-*`) | Your choice | Disable specific sections |
  180. | **Xpool safe** (`--xpool-safe`) | 84 | Disable CDP function tools that trigger `Runtime.enable` |
  181. ```bash
  182. stealth-browser-mcp --minimal
  183. stealth-browser-mcp --disable-cdp-functions --disable-dynamic-hooks
  184. stealth-browser-mcp --list-sections
  185. stealth-browser-mcp --debug
  186. stealth-browser-mcp --transport http --host 127.0.0.1 --port 8000
  187. ```
  188. From a clone, `python src/server.py` takes the same flags.
  189. 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.
  190. **Available sections:**
  191. | Section | Tools | Description |
  192. |---------|-------|-------------|
  193. | `browser-management` | 8 | Core browser operations |
  194. | `element-interaction` | 13 | Page interaction and manipulation |
  195. | `element-extraction` | 9 | Element cloning and extraction |
  196. | `file-extraction` | 9 | File-based extraction tools |
  197. | `network-debugging` | 10 | Network monitoring and capture |
  198. | `cdp-functions` | 17 | Chrome DevTools Protocol execution |
  199. | `progressive-cloning` | 10 | Advanced element cloning |
  200. | `cookies-storage` | 3 | Cookie management |
  201. | `tabs` | 5 | Tab management |
  202. | `debugging` | 7 | Debug and system tools |
  203. | `dynamic-hooks` | 10 | AI-assisted network hooks |
  204. ---
  205. ## Server Configuration
  206. These are environment variables for the MCP server process. Set them in your shell, service manager, Docker environment, or MCP client `env` block.
  207. | Variable | Default | Meaning |
  208. |----------|---------|---------|
  209. | `STEALTH_BROWSER_MCP_AUTH_TOKEN` | unset | Optional bearer token for HTTP transport. When set, HTTP clients must send `Authorization: Bearer <token>`. |
  210. | `MCP_AUTH_TOKEN` | unset | Backward-compatible alias for `STEALTH_BROWSER_MCP_AUTH_TOKEN`. |
  211. | `BROWSER_IDLE_TIMEOUT` | `600` | Global idle timeout in seconds before an unused browser instance is auto-closed. Set `0` to disable idle reaping globally. |
  212. | `BROWSER_IDLE_REAPER_INTERVAL` | `60` | Background reaper check interval in seconds. |
  213. | `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. |
  214. | `BROWSER_ORPHAN_PROFILE_MAX_AGE` | `21600` | Startup cleanup threshold in seconds for stale `uc_*` temp profiles. Set `0` to disable this startup sweep. |
  215. | `STEALTH_BROWSER_EXECUTABLE` | auto-detect | Path to the Chrome, Chromium, or Edge executable to launch instead of the auto-detected one. |
  216. | `BROWSER_FILE_UPLOAD_ALLOWED_DIRS` | repo root or data dir | Directories that `file_upload()` may read from. Separate multiple roots with `;` on Windows or `:` on macOS/Linux. Defaults to the repo root for a clone and to the `uploads` folder in the data directory for an installed package. |
  217. | `STEALTH_BROWSER_MCP_DATA_DIR` | repo root or user data dir | Where element clones and large responses are written. Defaults to the repo root for a clone, and for an installed package to `%LOCALAPPDATA%\stealth-browser-mcp` on Windows, `~/Library/Application Support/stealth-browser-mcp` on macOS, or `$XDG_DATA_HOME/stealth-browser-mcp` (`~/.local/share/stealth-browser-mcp`) on Linux. |
  218. | `STEALTH_BROWSER_DEBUG` | `0` | Enable verbose debug logging to `stderr` when set to `1`. |
  219. | `DEBUG` | `0` | Legacy alias for `STEALTH_BROWSER_DEBUG`. |
  220. | `XPOOL_SAFE_MODE` | `0` | Disable the `cdp-functions` section at startup. |
  221. | `PORT` | `8000` | Default HTTP port when `--port` is not provided. |
  222. **PowerShell example:**
  223. ```powershell
  224. $env:STEALTH_BROWSER_MCP_AUTH_TOKEN='replace-with-a-long-random-token'
  225. $env:BROWSER_IDLE_TIMEOUT='900'
  226. $env:BROWSER_IDLE_REAPER_INTERVAL='30'
  227. $env:BROWSER_ORPHAN_PROFILE_MAX_AGE='43200'
  228. $env:BROWSER_FILE_UPLOAD_ALLOWED_DIRS='C:\Users\me\uploads;C:\Users\me\Documents'
  229. python src/server.py
  230. ```
  231. **MCP client `env` block:**
  232. ```json
  233. {
  234. "mcpServers": {
  235. "stealth-browser-mcp": {
  236. "command": "C:\\path\\to\\stealth-browser-mcp\\venv\\Scripts\\python.exe",
  237. "args": ["C:\\path\\to\\stealth-browser-mcp\\src\\server.py"],
  238. "env": {
  239. "STEALTH_BROWSER_MCP_AUTH_TOKEN": "replace-with-a-long-random-token",
  240. "BROWSER_IDLE_TIMEOUT": "900",
  241. "BROWSER_FILE_UPLOAD_ALLOWED_DIRS": "C:\\Users\\me\\uploads;C:\\Users\\me\\Documents"
  242. }
  243. }
  244. }
  245. }
  246. ```
  247. **HTTP client example:**
  248. ```python
  249. from fastmcp import Client
  250. from fastmcp.client.auth import BearerAuth
  251. client = Client(
  252. "http://127.0.0.1:8000/mcp/",
  253. auth=BearerAuth("replace-with-a-long-random-token"),
  254. )
  255. ```
  256. **Per-instance idle override:**
  257. - `spawn_browser(idle_timeout_seconds=1800)` keeps that instance for 30 minutes of inactivity.
  258. - `spawn_browser(idle_timeout_seconds=0)` disables idle reaping for that one instance.
  259. ---
  260. ## Toolbox
  261. <details>
  262. <summary><strong>Browser Management (8)</strong></summary>
  263. | Tool | Description |
  264. |------|-------------|
  265. | `spawn_browser()` | Create a stealth browser instance |
  266. | `list_instances()` | List active browser sessions |
  267. | `close_instance()` | Clean shutdown of a browser |
  268. | `get_instance_state()` | Full browser state information |
  269. | `navigate()` | Navigate to URLs |
  270. | `go_back()` | Navigate back in history |
  271. | `go_forward()` | Navigate forward in history |
  272. | `reload_page()` | Reload current page |
  273. </details>
  274. <details>
  275. <summary><strong>Element Interaction (13)</strong></summary>
  276. | Tool | Description |
  277. |------|-------------|
  278. | `query_elements()` | Find elements by CSS selector or XPath |
  279. | `click_element()` | Click an element |
  280. | `type_text()` | Human-like typing with newline support |
  281. | `paste_text()` | Instant text paste via CDP |
  282. | `press_key()` | Press a real key with trusted CDP key events (Enter, Tab, arrows, modifiers) |
  283. | `file_upload()` | Upload allowlisted local files to file inputs |
  284. | `select_option()` | Select dropdown options |
  285. | `get_element_state()` | Inspect element state |
  286. | `wait_for_element()` | Wait for an element |
  287. | `scroll_page()` | Scroll naturally |
  288. | `execute_script()` | Run page JavaScript |
  289. | `get_page_content()` | Read page HTML and text |
  290. | `take_screenshot()` | Capture screenshots |
  291. `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.
  292. </details>
  293. <details>
  294. <summary><strong>Network Debugging (10)</strong></summary>
  295. | Tool | Description |
  296. |------|-------------|
  297. | `list_network_requests()` | List captured network requests |
  298. | `get_request_details()` | Inspect request headers and payload |
  299. | `get_response_details()` | Inspect response metadata |
  300. | `get_response_content()` | Read captured response content |
  301. | `search_network_requests()` | Search captured requests |
  302. | `export_network_data()` | Export captured network data |
  303. | `import_network_data()` | Import captured network data |
  304. | `set_network_capture_filters()` | Configure capture filters |
  305. | `get_network_capture_filters()` | Read active capture filters |
  306. | `modify_headers()` | Add or replace request headers |
  307. </details>
  308. <details>
  309. <summary><strong>Cookies and Storage (3)</strong></summary>
  310. | Tool | Description |
  311. |------|-------------|
  312. | `get_cookies()` | Read cookies |
  313. | `set_cookie()` | Set cookies |
  314. | `clear_cookies()` | Clear cookies |
  315. </details>
  316. <details>
  317. <summary><strong>Debugging (7)</strong></summary>
  318. | Tool | Description |
  319. |------|-------------|
  320. | `get_debug_view()` | Debug logs and statistics with pagination |
  321. | `clear_debug_view()` | Clear debug logs |
  322. | `export_debug_logs()` | Export logs as JSON, pickle, or gzip |
  323. | `get_debug_lock_status()` | Inspect debug logger lock state |
  324. | `hot_reload()` | Reload modules without server restart |
  325. | `reload_status()` | Check module reload status |
  326. | `validate_browser_environment_tool()` | Diagnose browser/platform compatibility |
  327. </details>
  328. <details>
  329. <summary><strong>Tabs (5)</strong></summary>
  330. | Tool | Description |
  331. |------|-------------|
  332. | `list_tabs()` | List open tabs |
  333. | `switch_tab()` | Change active tab |
  334. | `close_tab()` | Close a tab |
  335. | `get_active_tab()` | Get current active tab |
  336. | `new_tab()` | Create a new tab |
  337. </details>
  338. <details>
  339. <summary><strong>Element Extraction (9)</strong></summary>
  340. | Tool | Description |
  341. |------|-------------|
  342. | `extract_element_styles()` | Extract computed CSS properties |
  343. | `extract_element_structure()` | Extract DOM structure |
  344. | `extract_element_events()` | Extract event listeners |
  345. | `extract_element_animations()` | Extract animations and transitions |
  346. | `extract_element_assets()` | Extract images, fonts, videos, and assets |
  347. | `extract_element_styles_cdp()` | Pure CDP style extraction |
  348. | `extract_related_files()` | Find related CSS/JS files |
  349. | `clone_element_complete()` | Complete element cloning |
  350. | `extract_complete_element_cdp()` | Complete CDP-based element clone |
  351. </details>
  352. <details>
  353. <summary><strong>Progressive Cloning (10)</strong></summary>
  354. | Tool | Description |
  355. |------|-------------|
  356. | `clone_element_progressive()` | Initial lightweight element clone |
  357. | `expand_styles()` | Expand styles on demand |
  358. | `expand_events()` | Expand events on demand |
  359. | `expand_children()` | Expand child nodes on demand |
  360. | `expand_css_rules()` | Expand CSS rule data |
  361. | `expand_pseudo_elements()` | Expand pseudo-elements |
  362. | `expand_animations()` | Expand animation data |
  363. | `list_stored_elements()` | List stored progressive clones |
  364. | `clear_stored_element()` | Clear one stored element |
  365. | `clear_all_elements()` | Clear all stored elements |
  366. </details>
  367. <details>
  368. <summary><strong>File-Based Extraction (9)</strong></summary>
  369. | Tool | Description |
  370. |------|-------------|
  371. | `clone_element_to_file()` | Save complete clone to file |
  372. | `extract_complete_element_to_file()` | Save complete extraction to file |
  373. | `extract_element_styles_to_file()` | Save styles to file |
  374. | `extract_element_structure_to_file()` | Save structure to file |
  375. | `extract_element_events_to_file()` | Save events to file |
  376. | `extract_element_animations_to_file()` | Save animations to file |
  377. | `extract_element_assets_to_file()` | Save assets to file |
  378. | `list_clone_files()` | List saved clone files |
  379. | `cleanup_clone_files()` | Clean up old clone files |
  380. </details>
  381. <details>
  382. <summary><strong>CDP Function Execution (14)</strong></summary>
  383. | Tool | Description |
  384. |------|-------------|
  385. | `list_cdp_commands()` | List available CDP commands |
  386. | `execute_cdp_command()` | Run direct CDP commands |
  387. | `add_script_to_evaluate_on_new_document()` | Install scripts before page JavaScript runs |
  388. | `get_execution_contexts()` | List JavaScript execution contexts |
  389. | `discover_global_functions()` | Find global JavaScript functions |
  390. | `discover_object_methods()` | Discover methods on JavaScript objects |
  391. | `call_javascript_function()` | Execute a discovered JavaScript function |
  392. | `inspect_function_signature()` | Inspect function details |
  393. | `inject_and_execute_script()` | Inject and run custom JavaScript |
  394. | `create_persistent_function()` | Create functions that survive reloads |
  395. | `create_page_binding()` | Expose `window.<name>()` so page JavaScript can call back to the agent |
  396. | `get_page_binding_calls()` | Read queued page binding calls, optionally waiting for one |
  397. | `resolve_page_binding_call()` | Answer a page binding call with a value or an error |
  398. | `remove_page_binding()` | Remove a page binding and reject its pending calls |
  399. | `execute_function_sequence()` | Execute ordered function calls |
  400. | `execute_python_in_browser()` | Translate Python to JavaScript with py2js and run it |
  401. | `get_function_executor_info()` | Inspect executor state |
  402. </details>
  403. <details>
  404. <summary><strong>Dynamic Hooks (10)</strong></summary>
  405. | Tool | Description |
  406. |------|-------------|
  407. | `create_dynamic_hook()` | Create a restricted Python network hook |
  408. | `create_simple_dynamic_hook()` | Create hooks from common presets |
  409. | `list_dynamic_hooks()` | List active hooks |
  410. | `get_dynamic_hook_details()` | Inspect hook source and metadata |
  411. | `remove_dynamic_hook()` | Remove a hook |
  412. | `get_hook_documentation()` | Read request object and action docs |
  413. | `get_hook_examples()` | View hook examples |
  414. | `get_hook_requirements_documentation()` | Read matching and best-practice docs |
  415. | `get_hook_common_patterns()` | Common hook patterns |
  416. | `validate_hook_function()` | Validate hook code before use |
  417. </details>
  418. ---
  419. ## Stealth vs Playwright MCP
  420. Detection results are point-in-time and depend on site policy, region, browser version, IP reputation, and detector version. See [STEALTH_TESTS.md](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/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.
  421. | Feature | Stealth Browser MCP | Playwright MCP |
  422. |---------|---------------------|----------------|
  423. | Cloudflare / Queue-It style checks | Passes common JS challenges in testing | Commonly blocked |
  424. | Hardened sites | Uses real Chrome-family browser instances through nodriver | Frequently flagged as automation |
  425. | Login-walled pages | Can inspect loaded content and overlays through CDP | Often requires manual scripting |
  426. | UI element cloning | CDP-accurate extraction | Limited |
  427. | Network debugging | Full request/response inspection through AI tools | Basic |
  428. | API reverse engineering | Payload inspection through chat | Manual tools only |
  429. | Dynamic hook system | Restricted Python hooks for real-time interception | Not available |
  430. | Modular architecture | 11 sections, 21-101 tools | Fixed tool surface |
  431. | Total tools | 101 customizable tools | About 20 |
  432. ---
  433. ## Troubleshooting
  434. **No compatible browser found**
  435. Install Chrome, Chromium, or Microsoft Edge. The server auto-detects the first available browser. Run `validate_browser_environment_tool()` to diagnose.
  436. **Tools hang or return malformed JSON**
  437. 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.
  438. **Need verbose diagnostics without noisy normal runs**
  439. 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.
  440. **Browser crashes on Linux, Docker, or CI**
  441. 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.
  442. **Orphan Chromium processes or `uc_*` temp profiles accumulate**
  443. 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.
  444. **macOS disk fills up with `code_sign_clone` folders**
  445. Older versions let Chrome copy its app bundle into `com.google.Chrome.code_sign_clone` at every launch, and the copy stayed behind when an instance crashed or was killed. The server now launches Chrome with `MacAppCodeSignClone` turned off, so no new copies are made. To remove copies left by older versions, quit Chrome and run `rm -rf /private/var/folders/*/*/X/com.google.Chrome.code_sign_clone` (use `com.microsoft.edgemac.code_sign_clone` for Edge).
  446. **Too many tools cluttering the AI chat**
  447. Use `--minimal` for 20 core tools, `--xpool-safe` for xpool-compatible operation, or selectively disable sections:
  448. ```bash
  449. python src/server.py --disable-cdp-functions --disable-dynamic-hooks --disable-progressive-cloning
  450. ```
  451. **Module not found errors**
  452. Make sure you activated the virtual environment and installed dependencies:
  453. ```bash
  454. pip install -r requirements.txt
  455. ```
  456. ---
  457. ## Examples
  458. - **Market research** - Extract pricing and features from competitors, then output a comparison table.
  459. - **UI cloning** - Recreate a pricing section with exact fonts, styles, assets, and interactions.
  460. - **Inventory monitoring** - Watch a product page and alert when stock changes.
  461. - **API reverse engineering** - Intercept requests, map endpoints, and inspect data flow.
  462. - **Form automation** - Upload files from allowlisted paths and verify resulting page state.
  463. All driven from a single AI agent conversation.
  464. ---
  465. ## Showcase
  466. <div align="center">
  467. <img src="https://raw.githubusercontent.com/vibheksoni/stealth-browser-mcp/master/media/AugmentHeroClone.PNG" alt="Augment Code Hero Recreation" width="700" style="border-radius: 8px;">
  468. </div>
  469. **Augment Code hero clone** - A user asked Claude to clone the hero section from [augmentcode.com](https://www.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.
  470. [View the recreation](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/demo/augment-hero-recreation.html) | [Full walkthrough](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/demo/augment-hero-clone.md)
  471. ---
  472. ## Roadmap
  473. See the live plan in [ROADMAP.md](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/ROADMAP.md). Contributions welcome.
  474. ---
  475. ## Contributing
  476. Read [CONTRIBUTING.md](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/CONTRIBUTING.md) and open a PR. First-time contributors welcome.
  477. If this project saves you time, star the repo. It helps more than you think.
  478. ---
  479. ## Support
  480. If this tool saved you time or made you money, consider supporting development:
  481. - [Buy me a coffee](https://buymeacoffee.com/vibheksoni)
  482. ---
  483. ## License
  484. MIT - see [LICENSE](https://github.com/vibheksoni/stealth-browser-mcp/blob/master/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.