🦁 Real Browser MCP

A production-ready Model Context Protocol (MCP) server that equips AI agents with a reliable, controlled web browser for automation and testing. Built on Patchright (a hardened Playwright fork) and integrated with Ghostery Adblocker, Ghost Cursor (natural mouse dynamics), and an automation assistant for Cloudflare Turnstile challenges.

This server is 100% compatible with all major AI IDEs (Cursor, VS Code, Cline, Roo Code, Windsurf, PearAI, OpenCode, Kilo Code, and Claude Desktop) using standard STDIO communication.

📋 See POLICY.md for acceptable use guidelines. This tool is intended for QA, testing, accessibility automation, and authorized research.

⚙️ Installation & Setup

Since this project is published on NPM, you can run it either globally via npx / npm, or locally by building from source.

⚡ Quick Start (Using npx)

Add the following to your MCP Configuration file (e.g. cline_mcp_settings.json, claude_desktop_config.json, or Cursor):

{
  "mcpServers": {
    "real-browser": {
      "command": "npx",
      "args": ["-y", "real-browser-mcp-server@latest", "mcp"]
    }
  }
}

💻 Local Run (Direct Source / Pre-built)

If running directly from the local repository build:

{
  "mcpServers": {
    "real_browser_mcp_server": {
      "command": "node",
      "args": [
        "E:/Github-Software/Real-Browser-Mcp/dist/src/index.js"
      ],
      "env": {
        "AI_HEALING": "true",
        "HEADLESS": "false"
      }
    }
  }
}

🌍 Global Installation

Install it globally on your system. The hardened browser (Patchright Chromium) is downloaded automatically during install — no extra steps needed:

# One command: installs the server AND auto-downloads Patchright Chromium
npm install -g real-browser-mcp-server

# Run the MCP server
real-browser-mcp mcp

npx patchright install chromium

🛠️ Local Development & Build (Git Clone)

If you want to clone the repository and run it locally, follow these exact steps:

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

# 2. Navigate to the project directory
cd Real-Browser-Mcp

# 3. Install dependencies (Patchright Chromium is auto-downloaded via postinstall)
npm install

# 4. Build the TypeScript files
npm run build

# 5. Start the MCP server
npm run mcp

🐳 Run via Docker (Recommended for Servers)

We automatically build and publish a production-ready Docker image to GitHub Container Registry (GHCR).

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

# Run the MCP Server (Interactive stdio mode for AI IDEs)
docker run -i --rm ghcr.io/codeiva11/real-browser-mcp:latest

(Note: When running via Docker, it automatically runs in headless mode.)

Related MCP server: cloakbrowser-mcp

🚀 Key Automation & Reliability Features

• Reliable Browser Engine: Powered by Patchright Chromium, a hardened Playwright fork that reduces false-positives in automation environments (does not expose automation indicators or Webdriver/BiDi flags).

• Integrated Ad & Tracker Blocker: Utilizes @ghostery/adblocker-playwright with in-memory prebuilt filter lists (no disk cache), blocking ads and speed-bumps.

• Natural Interactions: Integrates ghost-cursor-patchright (Bézier curves) to simulate natural mouse movements, velocity, and hover-before-click behaviors. Features Physics-based Smooth Scrolling (page.realScroll) utilizing real mouse-wheel events and Cubic Ease-Out deceleration to mimic manual trackpad/mouse flicks for reliable interaction with dynamic UIs.

• Human-like Browsing: see_page lets the AI agent plan an entire multi-step task from one view and execute all actions in a single continuous flow via its unified steps workflow — no screenshot pause after every micro-step, just like a human. (The previously separate browse_task tool is now merged into see_page to avoid agent confusion.)

• Rich Single-Shot Vision: see_page now returns a screenshot plus full page text, all interactive elements with selectors, and an iframe inventory in one call — eliminating the need to re-capture the same page repeatedly.

• Turnstile Assist: Detects and assists with Cloudflare Turnstile challenges on pages you are authorized to access.

• Anti-Race Condition Guards: Robust state-guards ensure popup blockers, shims, and adblockers attach exactly once per page, preventing context destruction.

• TypeScript: Entire codebase is written in TypeScript with strict: true for type safety and maintainability.

🛠️ AI IDE Compatibility & Configuration Guide

Since this server adheres strictly to the official Model Context Protocol (MCP) specification over STDIO (with all informational logging directed safely to stderr to avoid JSON-RPC corruption), it is fully compatible with every modern AI editor.

1. Claude Desktop

Add the following to your claude_desktop_config.json:

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

2. Cursor IDE

1. Open Cursor Settings ➔ Features ➔ MCP.

2. Click + Add New MCP Server.

3. Configure as follows:

   • Name: real-browser-mcp-server

   • Type: command

   • Command: npx -y real-browser-mcp-server@latest mcp

4. Click Save.

3. Cline / Roo Code (VS Code)

Add the server entry to your global MCP settings file (typically found at %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json):

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

4. Kilo Code (VS Code)

Add the server entry to your ~/.config/kilo/kilo.jsonc (global) or project kilo.jsonc:

Option A: Local Clone (Recommended for development)

{
  "mcp": {
    "real_browser_mcp_server": {
      "type": "local",
      "command": [
        "node",
        "E:/Github-Software/Real-Browser-Mcp/dist/src/index.js"
      ],
      "environment": {
        "HEADLESS": "false",
        "AI_HEALING": "true"
      },
      "enabled": true
    }
  }
}

Option B: Global via npx (Windows) On Windows, call through cmd.exe /c npx so the batch script resolves cleanly:

{
  "mcp": {
    "real_browser_mcp_server": {
      "type": "local",
      "command": ["cmd.exe", "/c", "npx", "-y", "real-browser-mcp-server@latest", "mcp"],
      "environment": {
        "HEADLESS": "false",
        "AI_HEALING": "true"
      },
      "enabled": true
    }
  }
}

Option C: Global via npx (macOS / Linux)

{
  "mcp": {
    "real_browser_mcp_server": {
      "type": "local",
      "command": ["npx", "-y", "real-browser-mcp-server@latest", "mcp"],
      "environment": {
        "HEADLESS": "false",
        "AI_HEALING": "true"
      },
      "enabled": true
    }
  }
}

5. Windsurf IDE

Configure the server in your ~/.codeium/windsurf/mcp_config.json:

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

6. PearAI

Add the configuration via PearAI Settings ➔ MCP Servers using the standard command setup:

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

7. OpenCode AI IDE

Configure the server in your opencode.jsonc or standard MCP settings configuration:

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

⚙️ Environment Variables

You can configure browser_init defaults directly from the MCP client env block, without passing parameters on every call. Explicit parameters passed to browser_init always override these environment variables.

Values are case-insensitive. Priority for each option is: explicit browser_init param > environment variable > built-in default.

⚠️ Tool-result content safety: some AI providers (e.g. Anthropic) run safety classifiers on tool results, not just tool definitions. Tool payloads in this server are written content-neutral on purpose — do not patch instructions into tool results telling the model to "read the verification image and type the answer", or you will get [400]: content-blocked.

🛡️ Input caps (hard limits): press_key.count ≤ 100, click.clickCount ≤ 50, see_page.steps ≤ 100, media_extractor batch_extract.urls ≤ 50, execute_js.code ≤ 200k chars. Values beyond these are clamped with a warning — a runaway agent can never lock the server for hours.

🌐 Complete MCP Tool Reference (21 Tools)

The server exposes 18 tools categorized into functional units:

🌐 Browser & Session

🧭 Navigation & Tab Management

👆 Natural Interaction

📄 Extraction & Decoding

📡 Network & Utilities

👁️ AI Vision & Human-like Workflow

Human-like Workflow Pattern:

OLD (repetitive): see_page → click → see_page → type → see_page → click ...
NEW (human-like): see_page (once, fullPage) → steps:[click, type, scroll, extract] → see_page (only on page change)

If the current model cannot consume images, see_page still returns a full text + JSON summary, and solve_captcha can return text-only fallback guidance when called with preferTextFallback: true.

🛡️ Stealth & Anti-Bot Detection Bypass

With the right setup, Real-Browser-MCP is considered undetectable. Built on a hardened Patchright Chromium core with dynamic client hints, third-party storage partitioning preservation, Ghostery adblocking, and Ghost Cursor human dynamics, the core engine passes:

• Cloudflare (Turnstile, WAF, Managed Challenge) ✅

• Datadome ✅

• Akamai ✅

• Kasada ✅

• Shape / F5 ✅

• Bet365 ✅

• Fingerprint.com ✅

• Rebrowser Bot Detector (Storage Partitioning & CDP Clean) ✅

• Pixelscan (Bot Check & Fingerprint Clean) ✅

• CreepJS ✅

• Sannysoft ✅

• Incolumitas ✅

• IPHey ✅

• Browserscan ✅

• Brotector ✅

📈 Reliability & Test Coverage

Our test suites cover several real-world pages. Results depend on environment, third-party site changes, and network conditions.

🧪 Local Test Suite (100% Pass in CJS & ESM)

Every check in the live-site suite is strict: a failing check fails the run. Nothing is ever skipped.

💻 Programmatic Usage (Node.js SDK)

You can also use the core browser connector directly in your custom Node.js scripts.

CommonJS

const { connect } = require('real-browser-mcp-server');

(async () => {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true
  });

  await page.goto('https://example.com');

  // Natural mouse movement and click
  await page.realClick('#my-button');

  // Natural smooth scrolling (60FPS Cubic Ease-Out physics)
  await page.realScroll(400); // scrolls down 400px smoothly

  await browser.close();
})();

ESM (ECMAScript Modules)

import { connect } from 'real-browser-mcp-server';

const { browser, page } = await connect({
  headless: false,
  turnstile: true
});

await page.goto('https://example.com');
await page.realClick('#my-button');

// Natural smooth scrolling (60FPS Cubic Ease-Out physics)
await page.realScroll(400); // scrolls down 400px smoothly

await browser.close();

⌨️ NPM Script Commands

Run these scripts from the project root directory:

Every check in the live-site suite is strict: a failing check (e.g. reCAPTCHA v3 score below 0.9) fails the run. Nothing is ever skipped.

🏗️ Architecture Notes

Design

• MCP-first: every tool is defined in src/shared/tools.ts and dispatched through a single executeTool() router.

• Handler modules: src/mcp/handlers/ contains focused files — network-recorder.ts, network-extractors.ts, vision-captcha.ts, vision-see-page.ts, media-handlers.ts — with thin wrappers (network.ts, vision.ts, index.ts) for the tool-facing API.

• Browser state: a single global state object in src/mcp/handlers/state.ts holds the current browser/page instance and network recorder data. requireBrowser() / getState() provide typed accessors for handlers.

• Human-like workflow: the unified see_page steps[] workflow orchestrates the existing click/type/scroll/press_key/wait/extract handlers in a continuous sequence — no extra LLM or API key required. The AI agent (LLM client) plans the steps; see_page executes them without pausing.

• No project pollution: runtime caches (User-Agent detection, saved sessions) are written to the OS temp directory (os.tmpdir()/real-browser-mcp), never inside the project or working directory. The server does not create a .cache folder in your project tree.

• execute_js caveat: the execute_js tool runs arbitrary JavaScript inside the controlled browser page context (a sandboxed browser tab). Only invoke it with trusted input.

Known Limitations

• Single-session model: the MCP server manages one browser instance at a time. Concurrent multi-session isolation is not supported.

• reCAPTCHA / hCaptcha: detected honestly but not solved automatically. Use a third-party service for these.

• Vision tools require image-capable models: see_page and solve_captcha return images. Non-vision models get a full text + JSON summary fallback.

• TypeScript strict mode: the project compiles with strict: true across all source files, and noEmitOnError: true makes a type error fail the build outright (tsc --noEmit passes cleanly).

🛡️ License

This project is licensed under the ISC License. Created and maintained by codeiva11.