Skip to content
Back to search

Real-Browser-Mcp

A production-ready Model Context Protocol (MCP) server that equips AI agents with a reliable, controlled, and undetectable web browser for automation, scraping, and testing. Built on Patchright (a…

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/codeiva11--real-browser-mcp"><img src="/api/listings/codeiva11--real-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.

Since this project is published on NPM as [`real-browser-mcp-server`](https://www.npmjs.com/package/real-browser-mcp-server), you can run it instantly via `npx`, install it globally via `npm`, or build from source.

⚡ Quick Start (Recommended via npx)

Add the following to your AI client's MCP configuration file (e.g. `claude_desktop_config.json`, `cline_mcp_settings.json`, or Cursor):

{
  "mcpServers": {
    "real-browser": {
      "command": "npx",
      "args": ["-y", "real-browser-mcp-server@latest", "mcp"],
      "env": {
        "HEADLESS": "false",
        "AI_HEALING": "true",
        "TURNSTILE": "true"
      }
    }
  }
}

---

🌍 Global Installation

Install globally on your system. The hardened browser (Patchright Chromium) is **automatically downloaded** during installation:

# 1. Install globally (auto-downloads matching Patchright Chromium)
npm install -g real-browser-mcp-server

# 2. Run the MCP server
real-browser-mcp mcp

# Or check all registered tools
real-browser-mcp --list

> [!NOTE] > The `postinstall` step automatically runs `patchright install chromium`, which detects your OS and CPU architecture (Windows / Linux / macOS × x64 / arm64) and fetches the correct browser binary. If auto-download is skipped (e.g., in air-gapped or CI environments), run: > ```bash > npx patchright install chromium > ``` > To skip browser binary download during package builds, set `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`.

---

🛠️ Local Development & Build (From Git Source)

To clone, develop, or run locally:

# 1. Clone the repository
git clone https://github.com/codeiva11/Real-Browser-Mcp.git

# 2. Navigate to project root
cd Real-Browser-Mcp

# 3. Install dependencies (Chromium binary auto-downloads via postinstall)
npm install

# 4. Build TypeScript to dist/ and generate ESM wrappers
npm run build

# 5. Launch MCP Server
npm run mcp

Running Local Build in MCP Config:

{
  "mcpServers": {
    "real-browser-local": {
      "command": "node",
      "args": [
        "<path-to-repository>/Real-Browser-Mcp/dist/src/index.js",
        "mcp"
      ],
      "env": {
        "HEADLESS": "false",
        "AI_HEALING": "true"
      }
    }
  }
}

---

🐳 Run via Docker (For Headless & Server Environments)

A production-ready Docker container is published to the GitHub Container Registry (GHCR):

# Pull the latest image
docker pull ghcr.io/codeiva11/real-browser-mcp:latest

# Run the MCP Server in interactive stdio mode
docker run -i --rm ghcr.io/codeiva11/real-browser-mcp:latest

---

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 · 357 lines
  1. # 🦁 Real Browser MCP
  2. [![npm version](https://img.shields.io/npm/v/real-browser-mcp-server.svg)](https://www.npmjs.com/package/real-browser-mcp-server)
  3. [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen.svg)](https://nodejs.org/)
  4. [![Build & Test](https://github.com/codeiva11/Real-Browser-Mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/codeiva11/Real-Browser-Mcp/actions/workflows/publish.yml)
  5. [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
  6. A production-ready **Model Context Protocol (MCP)** server that equips AI agents with a reliable, controlled, and undetectable web browser for automation, scraping, and testing. Built on **Patchright** (a stealth-hardened Playwright fork) and integrated with **Ghostery Adblocker**, **Ghost Cursor** (natural human mouse dynamics), **Web Worker Consistency**, and an advanced automated solver for **Cloudflare Turnstile & WAF Managed Challenges**.
  7. This server is **100% compatible with all major AI IDEs and clients** (Cursor, Antigravity, Claude Desktop, VS Code, Cline, Roo Code, Windsurf, PearAI, OpenCode, and Kilo Code) using standard **STDIO** communication.
  8. > 📋 See [POLICY.md](./POLICY.md) for acceptable use guidelines. This tool is intended for QA, testing, accessibility automation, and authorized research.
  9. ---
  10. ## ⚙️ Installation & Setup
  11. Since this project is published on NPM as [`real-browser-mcp-server`](https://www.npmjs.com/package/real-browser-mcp-server), you can run it instantly via `npx`, install it globally via `npm`, or build from source.
  12. ### ⚡ Quick Start (Recommended via npx)
  13. Add the following to your AI client's MCP configuration file (e.g. `claude_desktop_config.json`, `cline_mcp_settings.json`, or Cursor):
  14. ```json
  15. {
  16. "mcpServers": {
  17. "real-browser": {
  18. "command": "npx",
  19. "args": ["-y", "real-browser-mcp-server@latest", "mcp"],
  20. "env": {
  21. "HEADLESS": "false",
  22. "AI_HEALING": "true",
  23. "TURNSTILE": "true"
  24. }
  25. }
  26. }
  27. }
  28. ```
  29. ---
  30. ### 🌍 Global Installation
  31. Install globally on your system. The hardened browser (Patchright Chromium) is **automatically downloaded** during installation:
  32. ```bash
  33. # 1. Install globally (auto-downloads matching Patchright Chromium)
  34. npm install -g real-browser-mcp-server
  35. # 2. Run the MCP server
  36. real-browser-mcp mcp
  37. # Or check all registered tools
  38. real-browser-mcp --list
  39. ```
  40. > [!NOTE]
  41. > The `postinstall` step automatically runs `patchright install chromium`, which detects your OS and CPU architecture (Windows / Linux / macOS × x64 / arm64) and fetches the correct browser binary. If auto-download is skipped (e.g., in air-gapped or CI environments), run:
  42. > ```bash
  43. > npx patchright install chromium
  44. > ```
  45. > To skip browser binary download during package builds, set `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`.
  46. ---
  47. ### 🛠️ Local Development & Build (From Git Source)
  48. To clone, develop, or run locally:
  49. ```bash
  50. # 1. Clone the repository
  51. git clone https://github.com/codeiva11/Real-Browser-Mcp.git
  52. # 2. Navigate to project root
  53. cd Real-Browser-Mcp
  54. # 3. Install dependencies (Chromium binary auto-downloads via postinstall)
  55. npm install
  56. # 4. Build TypeScript to dist/ and generate ESM wrappers
  57. npm run build
  58. # 5. Launch MCP Server
  59. npm run mcp
  60. ```
  61. #### Running Local Build in MCP Config:
  62. ```json
  63. {
  64. "mcpServers": {
  65. "real-browser-local": {
  66. "command": "node",
  67. "args": [
  68. "<path-to-repository>/Real-Browser-Mcp/dist/src/index.js",
  69. "mcp"
  70. ],
  71. "env": {
  72. "HEADLESS": "false",
  73. "AI_HEALING": "true"
  74. }
  75. }
  76. }
  77. }
  78. ```
  79. ---
  80. ### 🐳 Run via Docker (For Headless & Server Environments)
  81. A production-ready Docker container is published to the GitHub Container Registry (GHCR):
  82. ```bash
  83. # Pull the latest image
  84. docker pull ghcr.io/codeiva11/real-browser-mcp:latest
  85. # Run the MCP Server in interactive stdio mode
  86. docker run -i --rm ghcr.io/codeiva11/real-browser-mcp:latest
  87. ```
  88. ---
  89. ## 🚀 Key Automation & Stealth Features
  90. * **Undetectable Patchright Engine**: Built on hardened Patchright Chromium that strips CDP runtime evaluation markers, eliminates `navigator.webdriver`, preserves third-party storage partitioning, and normalizes Client Hints.
  91. * **Worker & Context Consistency**: Guarantees that `navigator.languages`, user agents, and hardware concurrency align 100% between the main page window and background **Web Workers** (passing Rebrowser consistency tests without discrepancy).
  92. * **Native Popup Blocking Emulation**: Mimics authentic Chrome popup blocking by returning `null` on untrusted script-initiated `window.open` calls while preserving real user click navigation.
  93. * **Turnstile & WAF Managed Challenge Assistant**: Automatically detects and assists with Cloudflare Turnstile checkboxes and WAF challenges on authorized pages, tracking dimensions, debouncing clicks, and verifying navigation.
  94. * **Ghost Cursor & Physics Scrolling**: Uses **ghost-cursor-patchright** (Bézier curves) for human-like cursor velocity, overshoot, and hover behaviors, plus 60FPS Cubic Ease-Out smooth scrolling (`page.realScroll`).
  95. * **Integrated Ad & Tracker Blocker**: In-memory prebuilt filter lists via `@ghostery/adblocker-playwright` block advertising scripts, cookie modals, and tracking beacons without disk overhead.
  96. * **Unified Single-Shot Vision (`see_page`)**: Returns a screenshot, parsed page text, interactive element selectors, and iframe inventory in one call. Supports multi-step action sequences (`steps[]`) to execute complex tasks continuously without LLM latency pauses.
  97. * **Long-Running Async Jobs (`async_job`)**: Long operations (batch extraction, multi-step navigation) can run in the background with `async: true` to prevent MCP client 60s watchdog timeouts.
  98. * **AI Healing Selectors**: Automatically detects and attempts alternative selector heuristics if dynamic CSS classes shift.
  99. * **Clean Process & State Isolation**: State guards prevent memory leaks; caches and recordings write strictly to OS temp storage, keeping your repository clean.
  100. ---
  101. ## 🛠️ AI IDE & Client Configuration Guide
  102. Since this server adheres strictly to the official Model Context Protocol (MCP) over **STDIO** (with all diagnostic logs routed to `stderr`), it connects smoothly to every modern AI IDE:
  103. ### 1. Claude Desktop
  104. Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
  105. ```json
  106. {
  107. "mcpServers": {
  108. "real-browser": {
  109. "command": "npx",
  110. "args": ["-y", "real-browser-mcp-server@latest", "mcp"],
  111. "env": {
  112. "HEADLESS": "false",
  113. "AI_HEALING": "true",
  114. "TURNSTILE": "true"
  115. }
  116. }
  117. }
  118. }
  119. ```
  120. ### 2. Cursor IDE
  121. 1. Open Cursor Settings ➔ **Features** ➔ **MCP Servers**.
  122. 2. Click **+ Add New MCP Server**.
  123. 3. Fill in:
  124. * **Name**: `real-browser`
  125. * **Type**: `command`
  126. * **Command**: `npx -y real-browser-mcp-server@latest mcp`
  127. 4. Click **Save**.
  128. ### 3. Google Antigravity / Windsurf / Cline / Roo Code
  129. Add to your client's MCP configuration file (e.g. `mcp_config.json` or `cline_mcp_settings.json`):
  130. ```json
  131. {
  132. "mcpServers": {
  133. "real-browser": {
  134. "type": "stdio",
  135. "command": "npx",
  136. "args": ["-y", "real-browser-mcp-server@latest", "mcp"],
  137. "env": {
  138. "HEADLESS": "false",
  139. "AI_HEALING": "true"
  140. },
  141. "disabled": false,
  142. "autoApprove": []
  143. }
  144. }
  145. }
  146. ```
  147. ### 4. Kilo Code (VS Code Extension)
  148. In `~/.config/kilo/kilo.jsonc` (or project `kilo.jsonc`):
  149. ```json
  150. {
  151. "mcp": {
  152. "real_browser_mcp_server": {
  153. "type": "local",
  154. "command": ["npx", "-y", "real-browser-mcp-server@latest", "mcp"],
  155. "environment": {
  156. "HEADLESS": "false",
  157. "AI_HEALING": "true"
  158. },
  159. "enabled": true
  160. }
  161. }
  162. }
  163. ```
  164. ---
  165. ## 🌐 Complete MCP Tool Reference (19 Registered Tools)
  166. The server exposes **19 specialized tools** across 8 functional categories:
  167. ### 🌐 1. Browser & Session Management (2 Tools)
  168. | Tool Name | Description | Key Parameters |
  169. |:---|:---|:---|
  170. | `browser_init` | Initialize or reconfigure a Patchright browser session with ad blocking, AI healing, fingerprint profiles, and WebRTC guards. | `headless`, `proxy`, `enableBlocker`, `aiHealing`, `widgetAssist`, `spoofFingerprint`, `blockWebRTCLeaks` |
  171. | `browser_close` | Gracefully shut down browser session and release active system handles. | `force` |
  172. ### 🧭 2. Navigation & Tabs (1 Tool)
  173. | Tool Name | Description | Key Parameters |
  174. |:---|:---|:---|
  175. | `navigate` | Navigate to URL or manage tabs (`list`, `switch`, `new`, `close`). Supports auto-switch on popups and `waitForChallenge` for Cloudflare interstitial challenges. | `url`, `tabAction`, `tabIndex`, `autoSwitchNewTab`, `waitUntil`, `timeout`, `waitForChallenge`, `challengeTimeout` |
  176. ### 👆 3. Natural Human Interaction (6 Tools)
  177. | Tool Name | Description | Key Parameters |
  178. |:---|:---|:---|
  179. | `click` | Natural click or drag-and-drop (`dragTo`) using Bézier curve movements, hover-first, and iframe support. | `selector`, `annotationId`, `dragTo`, `humanLike`, `hoverFirst`, `iframe`, `autoDetectPlayer` |
  180. | `type` | Natural typing with human-like keystroke intervals, smart clearing, and iframe support. | `selector`, `annotationId`, `text`, `clear`, `pressEnter`, `iframe` |
  181. | `solve_captcha` | Form and embedded verification widget assistant for authorized page testing. | `type`, `captchaSelector`, `formData`, `submit`, `preferTextFallback` |
  182. | `random_scroll` | Natural scrolling with lazy-load trigger detection and physics-based easing. | `direction`, `amount`, `smooth`, `aiDetectLazyLoad`, `iframe`, `iframeSelector` |
  183. | `press_key` | Keyboard key combination press with modifiers (Control, Shift, Alt, Meta). | `key`, `modifiers`, `count` |
  184. | `execute_js` | Execute JavaScript in page context, or execute session-replayed HTTP fetch calls. | `code`, `action`, `url`, `method`, `headers`, `body`, `async`, `iframe` |
  185. ### 📄 4. Extraction & Content (3 Tools)
  186. | Tool Name | Description | Key Parameters |
  187. |:---|:---|:---|
  188. | `get_content` | Retrieve page content formatted as `html`, `text`, `markdown`, `rawHttp`, or structured `elements`. | `format`, `selector`, `xpath`, `saveAs` |
  189. | `extract_data` | Extract structured data using regular expressions, JSON extraction, meta tags, or link discovery. | `type`, `pattern`, `source`, `transformKey` |
  190. | `media_extractor` | Detect, extract, and control video/audio playback streams (HLS, DASH, MP4). | `action`, `types`, `quality`, `playerAction` |
  191. ### 📡 5. Network & Traffic Control (2 Tools)
  192. | Tool Name | Description | Key Parameters |
  193. |:---|:---|:---|
  194. | `redirect_tracer` | Trace complete HTTP 301/302, JavaScript, and meta-refresh redirect chains. | `url`, `maxRedirects`, `decodeURLs` |
  195. | `network_recorder` | Capture and inspect HTTP/WebSocket traffic, export HAR archives, block unwanted asset patterns, and mock API endpoints. | `action`, `patterns`, `mock`, `captureXhrBody` |
  196. ### 🧠 6. Deep Analysis & Storage (2 Tools)
  197. | Tool Name | Description | Key Parameters |
  198. |:---|:---|:---|
  199. | `deep_analysis` | Deep inspection of DOM hierarchy, scripts, technologies, SEO meta, web vitals, and console error logs. | `types`, `detailed`, `detectAccessControls`, `includeWebPerf`, `includeConsole` |
  200. | `storage_inspector` | Inspect and manage cookies, localStorage, sessionStorage, IndexedDB, and encrypted state files. | `action`, `sessionPath`, `passphrase`, `enabled` |
  201. ### 👁️ 7. AI Vision & Multi-Step Task Runner (1 Tool)
  202. | Tool Name | Description | Key Parameters |
  203. |:---|:---|:---|
  204. | `see_page` | **Single-Shot Visual & Task Engine**: Captures full-page/viewport screenshot + page text + element selectors in one call. Execute an entire sequence of actions continuously via `steps[]` (`click`, `type`, `hover`, `scroll`, `wait`, `extract`) without repetitive roundtrips. | `fullPage`, `annotate`, `includePageText`, `scanIframes`, `steps[]`, `captureBefore`, `captureAfter`, `stopOnError` |
  205. ### 🛠️ 8. Utilities & Background Processing (2 Tools)
  206. | Tool Name | Description | Key Parameters |
  207. |:---|:---|:---|
  208. | `wait` | Smart wait for selectors, navigation lifecycle events, or fixed duration timers. | `type`, `value`, `timeout` |
  209. | `async_job` | Poll status or cancel background jobs dispatched with `async: true` (budget up to 10 minutes without MCP timeouts). | `action`, `jobId` |
  210. ---
  211. ## ⚙️ Environment Variables
  212. Configure default behavior globally from your MCP client's `env` block:
  213. | Variable | Values | Default | Description |
  214. |:---|:---|:---|:---|
  215. | `HEADLESS` | `true` / `false` | `false` (desktop) / `true` (CI) | Run browser in headless mode or visible window |
  216. | `AI_HEALING` | `true` / `false` | `true` | Auto-repair broken CSS selectors in `click`/`type` |
  217. | `ENABLE_BLOCKER` | `true` / `false` | `true` | Block ads, tracking trackers, and cookie notices |
  218. | `TURNSTILE` | `true` / `false` | `false` | Auto-assist with Cloudflare Turnstile & WAF challenges |
  219. | `REAL_BROWSER_ALLOW_PRIVATE_NETWORK` | `true` / `false` | `false` | Allow targeting localhost and private intranet IPs (SSRF protection) |
  220. | `REAL_BROWSER_TOOL_TIMEOUT_MS` | milliseconds | `120000` | Hard watchdog budget per tool execution |
  221. | `REAL_BROWSER_JOB_TIMEOUT_MS` | milliseconds | `600000` | Budget for background `async_job` executions (10 minutes) |
  222. | `INSPECT_DELAY_MS` | milliseconds | `0` (smart auto) | Hold delay for visual inspection during test suite runs |
  223. | `REAL_BROWSER_LOG_LEVEL` | `debug` / `info` / `warn` / `error` | `info` | Logging verbosity on `stderr` |
  224. ---
  225. ## 🛡️ Anti-Bot Detection Verification Matrix
  226. Real-Browser-MCP is rigorously tested against industry-standard detection test suites:
  227. | Target Detector | Signal Evaluated | Status |
  228. |:---|:---|:---|
  229. | **Rebrowser Bot Detector** | CDP leak, runtime evaluate, worker consistency & popup blocking | 🟢 100% Passed (All Green) |
  230. | **Sannysoft WebDriver** | `navigator.webdriver`, chrome runtime, permissions, plugins | 🟢 100% Passed |
  231. | **Cloudflare WAF** | Managed Challenge & interactive human verification | 🟢 100% Passed (Redirects in 13–22s) |
  232. | **Cloudflare Turnstile** | Embedded Turnstile iframe resolution & token delivery | 🟢 100% Passed |
  233. | **reCAPTCHA v3 Score** | Behavioral score evaluation | 🟢 100% Passed (Score ≥ 0.9) |
  234. | **Pixelscan Fingerprint** | Canvas/WebGL consistency & font coherence | 🟢 100% Passed (No Masking Detected) |
  235. | **Pixelscan Bot Check** | Automation framework detection heuristics | 🟢 100% Passed |
  236. ---
  237. ## 💻 Programmatic Usage (Node.js SDK)
  238. You can also import and use the real browser engine directly in your JavaScript / TypeScript projects:
  239. ### CommonJS (CJS)
  240. ```javascript
  241. const { connect } = require('real-browser-mcp-server');
  242. (async () => {
  243. const { browser, page } = await connect({
  244. headless: false,
  245. turnstile: true
  246. });
  247. await page.goto('https://example.com');
  248. await page.realClick('#my-button');
  249. await page.realScroll(500); // 60FPS physics smooth scroll
  250. await browser.close();
  251. })();
  252. ```
  253. ### ECMAScript Modules (ESM)
  254. ```javascript
  255. import { connect } from 'real-browser-mcp-server';
  256. const { browser, page } = await connect({
  257. headless: false,
  258. turnstile: true
  259. });
  260. await page.goto('https://example.com');
  261. await page.realClick('#my-button');
  262. await browser.close();
  263. ```
  264. ---
  265. ## ⌨️ NPM Script Commands
  266. | Command | Purpose |
  267. |:---|:---|
  268. | `npm start` | Launch the MCP server over standard STDIO transport. |
  269. | `npm run mcp` | Launch the MCP server. |
  270. | `npm run mcp:verbose` | Launch the MCP server with verbose tool catalog output on `stderr`. |
  271. | `npm run list` | Print all 19 registered MCP tools with categories. |
  272. | `npm run build` | Compile TypeScript (`tsc`) and generate CJS & ESM distributions. |
  273. | `npm test` | Run the full test suite across both CJS and ESM (14 tests total). |
  274. | `npm run cjs_test` | Run CommonJS test suite with smart adaptive inspection delay. |
  275. | `npm run esm_test` | Run ESM test suite with smart adaptive inspection delay. |
  276. ---
  277. ## 🛡️ License
  278. This project is licensed under the **ISC License**. Developed and maintained by [codeiva11](https://github.com/codeiva11).

Ratings and comments

Sign in to rate this skill.

Sign in

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