brave-real-browser-mcp-server

Brave Real Browser MCP Server

MCP Server for Puppeteer + Brave Browser + Stealth + Ad Blocker + Turnstile Auto-Solver

A production-ready MCP (Model Context Protocol) server that combines Puppeteer with Brave Browser for undetectable web automation. Passes all major bot detectors including Cloudflare, DataDome, and reCAPTCHA v3.

Key Features

Feature	Description
MCP Server	Model Context Protocol compatible server with 23 optimized tools
LSP Server	Language Server Protocol for IDE code intelligence
AI Core	Automatic AI enhancement for all tools (auto-healing, smart retry)
Brave Browser	Uses Brave instead of Chromium for better privacy
50+ Stealth Features	Passes all major bot detectors
Built-in Ad Blocker	45+ filter sources, 100/100 score, auto-update
Turnstile Auto-Solver	Cloudflare CAPTCHA bypass
Real Cursor	Ghost-cursor for human-like movements
Plugin Support	Puppeteer-extra plugins compatible
Proxy Support	Built-in proxy with authentication
Auto-Install	Brave auto-installs if missing
TypeScript Support	Full type definitions included
ESM + CJS	Dual module support
Multi-language	English & Hindi language support
Auto-Update	Daily automatic dependency updates
Auto-Publish	Automatic NPM publishing on updates
Monorepo	npm workspaces with linked packages
Singleton Blocker	Single shared blocker instance
Decoder Utilities	URL, Base64, AES decryption built-in
Batch Operations	Extract from multiple URLs/pages at once
Nested Iframe Support	Scan 3+ levels deep in iframes

MCP Server (Model Context Protocol)

This package is a fully-featured MCP Server with 23 optimized browser automation tools for AI assistants like Claude, Cursor, Copilot, and other MCP-compatible clients. Tools intelligently merged for maximum efficiency with AI auto-healing capabilities.

Quick Start MCP Server

# Start the MCP server
npm run dev

# Or with verbose mode (shows all tool details)
npm run mcp:verbose

MCP Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "brave-real-browser-mcp-server": {
      "command": "node",
      "args": [
        "C:/Users/Admin/Desktop/Brave-Real-Browser-Mcp-Server/dist/index.js"
      ],
      "env": {
        "HEADLESS": "false"
      }
    }
  }
}

"mcp": {
    "brave-real-browser-mcp-server": {
      "type": "local",
      "command": ["node", "c:\\Users\\Admin\\Desktop\\Brave-Real-Browser-Mcp-Server\\dist\\index.js"],
      "environment": {
        "HEADLESS": "false"
      },
      "enabled": true
    }
  },

Or if installed globally:

{
  "mcpServers": {
    "brave-browser": {
      "command": "brave-mcp"
    }
  }
}

Available MCP Tools (23 Optimized)

#	Tool	Description	Status
1	browser_init 🚀	Initialize Brave browser with 50+ stealth features, anti-detection, Turnstile auto-solver, proxy support, ad blocker, AI auto-healing	✅
2	navigate 🧭	Navigate to URL with smart retry (3 attempts), context recovery, AI healing, customizable wait strategies (load/DOMContentLoaded/networkidle)	✅
3	get_content 📄	Get page content in 4 formats: html (full HTML), text (plain), markdown (formatted), rawHttp (raw HTTP without JS — fast, bypasses JS protections). AI selector healing + attribute extraction	✅ Enhanced
4	wait ⏳	Smart wait: selector, navigation, timeout, networkidle, or AI-predicted optimal timing	✅
5	click 👆	Human-like click with ghost cursor, AI healing, iframe support, hover-first for dynamic controls, auto video player detection (JWPlayer/VideoJS/Plyr/VidStack/DooPlayer)	✅
6	type ⌨️	Type with human speed variation, smart clearing, iframe support, optional Enter key press	✅
7	browser_close 🔴	Close browser with cleanup, optional session save (cookies + storage)	✅
8	solve_captcha 🔓	Auto-solve: Turnstile, reCAPTCHA, hCaptcha (JS-based) + Text/Image OCR. Merged with form automation — AI field matching, human-like typing, auto-submit	✅
9	random_scroll 📜	Human-like scroll with AI pattern detection, lazy-load trigger, direction: up/down/random/smart	✅
10	find_element 🔍	Find elements by CSS selector, XPath, or text content. AI auto-heals broken selectors, extracts smart attributes	✅
11	save_content_as_markdown 📝	Save page as AI-cleaned Markdown file — removes ads/clutter, includes images and meta	✅
12	redirect_tracer 🔀	Trace full redirect chains: HTTP 301/302 + JS navigations (window.location, setTimeout) + meta refresh. Auto-decodes encoded URLs, returns status codes + headers	✅
13	extract_data 🔎	8 modes: regex, json, meta, structured, auto, deobfuscate (JS decode: _0x arrays, hex, unicode, eval, webpack, terser, string concat, rotation), apiDiscovery (hidden APIs via runtime interception), decrypt (Base64 chain, hex, URL, ROT13, AES-256-CBC + auto key extract)	✅ Power
14	press_key 🎹	Press keyboard keys with human-like timing, modifier support (Ctrl/Shift/Alt), repeat count	✅
15	progress_tracker 📈	Track automation progress (0-100%), AI estimates remaining time	✅
16	deep_analysis 🧠	Deep page analysis: DOM structure, scripts, anti-bot detection (Cloudflare/DataDome/reCAPTCHA), tech stack, SEO tags, security headers, AI scraping strategy recommendations	✅
17	network_recorder 📡	9 actions: start (+ inject API interceptors for fetch/XHR/sendBeacon + WebSocket interceptor), stop, get, clear, get_media (HLS/DASH/video), get_navigations (JS redirects), get_api_calls (with full request/response bodies), get_intercepted_apis (runtime monkey-patched calls), get_websockets (all WS connections + messages)	✅ Power
18	link_harvester 🔗	Extract all links: hidden (display:none), Base64/URL encoded, obfuscated (data attrs, JS vars), iframe links (multi-level), dynamic links. Auto-decode enabled	✅
19	cookie_manager 🍪	Cookie CRUD: get/set/delete/clear/export/import. AI optimizes session persistence	✅
20	file_downloader ⬇️	Download files with resume support, batch download (multiple URLs), auto-decode Base64/URL encoded URLs, AES decryption for encrypted files	✅
21	media_extractor 🎬	6 actions: extract (video/audio/HLS/DASH/download from page + 3+ level nested iframes), list_iframes, switch_iframe, player_control (JWPlayer/VideoJS/Plyr/VidStack/DooPlayer — play/pause/seek/sources), decode_url (auto/url/base64/aes), batch_extract	✅ New
22	execute_js 💻	Execute custom JavaScript: async support, error handling, iframe context execution (by index or selector), configurable timeout	✅
23	form_automator 📋	Smart form automation: AI field detection and matching, human-like typing, auto-fill, captcha integration, validation before submit	✅

Tool Optimization Summary

Merged Tools (5 → 2):

• ✅ iframe_handler + stream_extractor + player_api_hook → media_extractor
• ✅ search_regex + extract_json + scrape_meta_tags → extract_data
• ✅ get_content enhanced with js_scrape features

Benefits:

• 🎯 18% reduction in tool count (28 → 23)
• 🚀 Simpler API for AI agents
• 💪 More powerful combined features
• 🤖 AI-first design with auto-healing
• 📦 Decoder utilities built-in (URL, Base64, AES)

MCP Example Usage

User: Open a browser and go to example.com

AI: I'll use browser_init to start the browser, then navigate to the URL.

[Calls browser_init] -> Browser started
[Calls navigate with url="https://example.com"] -> Page loaded

User: Get all links on the page

AI: [Calls link_harvester] -> Found 15 links...

User: Download the main image

AI: [Calls file_downloader with url="..."] -> Downloaded to ./downloads/image.png

LSP Server (Language Server Protocol)

This package also includes a full-featured LSP Server for IDE code intelligence when writing browser automation scripts.

Quick Start LSP Server

# Start the LSP server
npm run lsp

LSP Capabilities

Feature	Description
Autocomplete	Tool names, parameters, and enum values
Hover	Full documentation on hover
Diagnostics	Error & warning detection (missing browser_init, etc.)
Snippets	Code templates for common workflows
Refactoring	Quick fixes (add browser_init, try-catch, etc.)
Simulation	Workflow simulation in IDE
Multi-language	English & Hindi support

VS Code Setup

Create .vscode/settings.json in your project:

{
  "braveRealBrowser.language": "en",
  "braveRealBrowser.maxDiagnostics": 100,
  "braveRealBrowser.enableSnippets": true,
  "braveRealBrowser.enableSimulation": true,
  "braveRealBrowser.enableRefactoring": true
}

Diagnostic Features

The LSP detects common issues:

• Missing browser_init() before page operations
• Missing navigate() before content extraction
• Invalid selectors and URLs
• Missing required parameters
• Unclosed browser sessions
• Security issues (eval usage, etc.)

Quick Fixes

When diagnostics are detected, quick fixes are offered:

• Add browser_init() at start
• Add navigate() before page tools
• Add browser_close() at end
• Wrap in try-catch
• Extract to function

AI Core (Automatic Enhancement)

All 23 tools are automatically enhanced with AI capabilities. No configuration needed - AI features work transparently.

How It Works

AI Agent calls any tool (e.g., click, type, find_element)
                │
                ▼
        ┌───────────────────┐
        │   AI Core Check   │
        │ (Lazy initialize) │
        └───────────────────┘
                │
                ▼
        Execute Original Tool
                │
        ┌───────┴───────┐
        │               │
     Success         Failed (selector not found)
        │               │
        ▼               ▼
   Return result    ┌─────────────────┐
   with _ai meta    │ AI Auto-Healing │
                    │ - Find alts     │
                    │ - Try healed    │
                    │ - Retry op      │
                    └─────────────────┘
                            │
                            ▼
                    Return healed result

AI Features

Feature	Description
Auto-Healing Selectors	If a CSS selector fails, AI finds alternative selectors
Smart Retry	Failed operations are automatically retried with AI assistance
Confidence Scoring	AI provides confidence scores for healed selectors
Caching	Healed selectors are cached for performance
Zero Configuration	Works out of the box with all 23 tools

Example Response with AI Metadata

When AI heals a broken selector:

{
  "success": true,
  "selector": "#new-login-btn",
  "clicked": true,
  "_ai": {
    "enabled": true,
    "healed": true,
    "originalSelector": "#old-login-button",
    "healedSelector": "#new-login-btn",
    "duration": 245
  }
}

AI Modules

Module	Description
AICore	Central AI intelligence singleton
ElementFinder	Smart element finding with multiple strategies
SelectorHealer	Auto-fix broken CSS selectors
PageAnalyzer	Page structure analysis
ActionParser	Natural language command parsing

Programmatic Access

For advanced usage, you can access AI features directly:

const { getAICore, aiEnhancedSelector } = require('./src/mcp/handlers');

// Get AI Core instance
const ai = getAICore();

// Use AI-enhanced selector finding
const { element, selector, healed } = await aiEnhancedSelector(page, '#old-selector', 'click');

Unified Architecture

Both MCP and LSP servers share the same tool definitions:

src/
├── shared/
│   └── tools.js         # Single source of truth (28 tools)
├── ai/                  # AI Core Module (Auto-enhancement)
│   ├── index.js         # AI module exports
│   ├── core.js          # AI Core singleton
│   ├── element-finder.js# Smart element finding
│   ├── selector-healer.js# Auto-heal selectors
│   ├── page-analyzer.js # Page analysis
│   └── action-parser.js # NL command parsing
├── mcp/
│   ├── server.js        # MCP server for AI agents
│   └── handlers.js      # Tool implementations + AI integration
├── lsp/
│   ├── server.js        # LSP server for IDEs
│   └── capabilities/    # Autocomplete, hover, diagnostics, etc.
└── index.js             # Unified entry point

Decoder Utilities (Built-in)

Powerful decoding capabilities for obfuscated content extraction:

Decoder	Description	Use Cases
URL Decoder	Multi-layer URL decoding	Obfuscated links, redirect chains
Base64 Decoder	Standard, URL-safe, padded variants	Encoded parameters, tokens
AES Decryptor	AES-256-CBC/ECB decryption	Encrypted streams, secure tokens
tryAll()	Attempts all decoders automatically	Unknown encoding detection

Usage Examples

// Automatic decoder (via media_extractor)
{
  "action": "decode_url",
  "encodedData": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
  "decoderType": "auto"  // Tries all decoders
}

// Manual decoding options
{
  "action": "decode_url",
  "encodedData": "U2Fsd2Fy...",
  "decoderType": "aes",
  "aesKey": "my-secret-key",
  "aesIV": "initialization-vec"
}

Real-World Example: Movie Download Chain

// 1. Navigate to movie page
{ "tool": "navigate", "params": { "url": "https://moviesdrive.surf/movies/dhurandhar-2025/" }}

// 2. Click download button to get redirect
{ "tool": "click", "params": { "selector": "#hubcloud-480p" }}

// 3. Trace full redirect chain
{ "tool": "redirect_tracer", "params": { "url": "current_page_url", "followJS": true }}

// 4. Extract and decode obfuscated links
{ "tool": "extract_data", "params": { 
  "type": "regex", 
  "pattern": "hubcloud\\.fans/drive/[^\"']+",
  "autoDecode": true  // Auto-decode found URLs
}}

// 5. Get direct download link from nested iframes
{ "tool": "media_extractor", "params": { 
  "action": "extract",
  "types": ["download"],
  "deep": true  // Scan nested iframes
}}

🔥 Deep Scraping Power Features

Advanced capabilities for bypassing obfuscation, intercepting hidden APIs, and decrypting encoded data.

1. Raw HTTP Mode (get_content)

Fetch raw HTML without JavaScript rendering — fast, lightweight, bypasses JS-based protections:

{ "tool": "get_content", "params": { "format": "rawHttp" }}
// Returns: raw HTML source code via Node.js fetch (no browser needed)

2. Enhanced Deobfuscation (extract_data)

Decode obfuscated JavaScript from any page:

{ "tool": "extract_data", "params": { "type": "deobfuscate" }}

Capability	Pattern
String arrays	var _0x3f0cd6 = [...]
Hex strings	'\x68\x74\x74\x70' → http
Unicode escapes	'\u0066\u0065\u0074\u0063\u0068' → fetch
Eval unpacker	eval(function(p,a,c,k,e,d){...})
Webpack modules	__webpack_require__, module.exports
Terser mappings	var a="fetch",b="POST"
String concat	"htt"+"ps://"+"api" → https://api
Array rotation	push(arr.shift()) patterns

3. API Discovery (extract_data)

Find hidden API endpoints via static analysis + runtime interception:

{ "tool": "extract_data", "params": { "type": "apiDiscovery" }}
// Returns: fetchEndpoints, xhrEndpoints, formActions, scriptSources, dynamicApis

4. Response Auto-Decryption (extract_data)

Auto-detect and decode encrypted/encoded data:

// Auto-decrypt with key extraction from page scripts
{ "tool": "extract_data", "params": { "type": "decrypt", "encryptedData": "base64string..." }}

// With explicit AES key
{ "tool": "extract_data", "params": { "type": "decrypt", "encryptedData": "...", "aesKey": "secret" }}

Decoder	Description
Base64 chain	Recursive decode up to 5 levels, auto-detect JSON
Hex	68747470733a2f2f → https://
URL decode	Multi-level %2F%2F → //
ROT13	Caesar cipher (reports if result contains URLs)
AES-256-CBC	With user key or auto-extracted key from CryptoJS patterns

5. Runtime API Interception (network_recorder)

Capture API calls from obfuscated/webpack code via pre-page-load monkey-patching:

// Start recording (injects interceptors via evaluateOnNewDocument)
{ "tool": "network_recorder", "params": { "action": "start" }}

// Navigate to page...

// Get intercepted APIs (caught from monkey-patched fetch/XHR/sendBeacon)
{ "tool": "network_recorder", "params": { "action": "get_intercepted_apis" }}
// Returns: { type, url, method, headers, body, timestamp }

6. WebSocket Recording (network_recorder)

Capture WebSocket connections and messages:

{ "tool": "network_recorder", "params": { "action": "get_websockets" }}
// Returns: { count, totalMessages, websockets: [{ id, url, status, messages }] }

7. XHR Body Capture (network_recorder)

Capture full request/response bodies for API calls:

{ "tool": "network_recorder", "params": { "action": "start", "captureXhrBody": true }}
// Later:
{ "tool": "network_recorder", "params": { "action": "get_api_calls" }}
// Returns: requestBody, responseBody, responseJson for each API call

Unified CLI

# List all tools (23 optimized)
node src/index.js --list

# Start MCP server (default)
node src/index.js mcp

# Start LSP server
node src/index.js lsp

# Show help
node src/index.js --help

Tool Categories

Category	Tools	Description
Browser	3	Browser lifecycle (init, close, cookies)
Navigation	1	Page navigation with smart retry
Interaction	4	User actions with AI healing (click, type, scroll, key press)
Extraction	5	Content scraping (get_content, extract_data, link_harvester, media_extractor, deep_analysis)
Network	3	Network operations (recorder, download, trace)
Analysis	2	Page analysis and form automation
Utility	5	Helpers (wait, progress, elements, cookies, JavaScript)

Monorepo Ecosystem

brave-real-browser-mcp-server (Top Level - MCP Server)
    └── brave-real-puppeteer-core (Stealth patches)
        └── brave-real-launcher (Browser launch)
            └── brave-real-blocker (Ad/Tracker blocking - Singleton)

Package Details

Package	Description	npm
brave-real-browser-mcp-server	MCP Server + Puppeteer integration
brave-real-puppeteer-core	50+ stealth patches for Puppeteer/Playwright
brave-real-launcher	Brave Browser launcher with auto-detection
brave-real-blocker	uBlock Origin-based ad/tracker blocker (45+ filter sources, 100/100 score)

Ad Blocker Features (brave-real-blocker)

Category	Details
Filter Sources	45+ lists (uBlock Origin, EasyList, AdGuard, Anti-Adblock, etc.)
Built-in Rules	200+ aggressive blocking rules
Protection Layers	5 layers (Ad blocking, Stealth, Scriptlets, Cosmetic, Redirect)
Test Score	AdBlock Tester: 100/100
Auto-Update	Filter lists cached 7 days, auto-refresh
Singleton	Single shared instance across ecosystem

Automation & CI/CD

GitHub Actions Workflows

Workflow	Schedule	Description
auto-update-deps.yml	Daily 6 AM UTC	Auto-updates all dependencies across all packages
monorepo-publish.yml	Daily 6 AM UTC + Push/PR	Version bump + NPM publish for all packages

Auto-Update Flow

Daily 6 AM UTC
      ↓
Check all packages for outdated dependencies
      ↓
┌─────────────────────────────────────────┐
│  brave-real-blocker                      │
│  brave-real-launcher                     │
│  brave-real-puppeteer-core               │
│  brave-real-browser-mcp-server           │
└─────────────────────────────────────────┘
      ↓
Update found? → Install → Build → Test → Commit → Push
      ↓
Trigger NPM Publish Workflow
      ↓
All packages published to NPM automatically

Dependencies Auto-Updated

Package	Auto-Updated Dependencies
blocker	@cliqz/adblocker-puppeteer, cross-fetch, fs-extra
launcher	which, escape-string-regexp, is-wsl
puppeteer-core	puppeteer-core, playwright-core, yargs
root	ghost-cursor, puppeteer-extra, puppeteer-extra-plugin-stealth

Installation

npm install brave-real-browser-mcp-server

For Linux (required for headless mode):

sudo apt-get install xvfb

Quick Start

CommonJS

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

(async () => {
  const { browser, page, blocker } = await connect({
    headless: false,
    turnstile: true,  // Auto-solve Cloudflare
  });

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

  // Human-like click with ghost-cursor
  await page.realClick('#button');

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

ESM

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

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

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

Connect Options

Option	Type	Default	Description
headless	boolean | 'new'	false	Headless mode (also respects .env HEADLESS variable)
args	string[]	[]	Additional Chrome flags
customConfig	object	{}	Brave launcher options
proxy	ProxyOptions	{}	Proxy configuration
turnstile	boolean	false	Auto-solve Cloudflare Turnstile
connectOption	object	{}	Puppeteer connect options
disableXvfb	boolean	false	Disable virtual display (Linux)
plugins	array	[]	Puppeteer-extra plugins
ignoreAllFlags	boolean	false	Override all default flags
enableBlocker	boolean	true	Enable ad/tracker blocker
blockerOptions	BlockerOptions	{}	Blocker configuration

BlockerOptions

Option	Type	Default	Description
enableAdBlocking	boolean	true	Network request blocking (Ads/Trackers)
enableStealth	boolean	true	Stealth evasions (Navigator, WebGL, etc.)
enableCosmeticFiltering	boolean	true	Element hiding (CSS-based)
enableRedirectBlocking	boolean	true	Popup and redirect blocking
enableScriptlets	boolean	true	Scriptlet injection for anti-adblock
customFiltersPath	string	null	Path to custom filter list file
enableFilterAutoUpdate	boolean	true	Auto-update uBlock Origin filters

ProxyOptions

Option	Type	Required	Description
host	string	Yes	Proxy host
port	number	Yes	Proxy port
username	string	No	Proxy username
password	string	No	Proxy password

Usage Examples

Proxy Configuration

const { browser, page } = await connect({
  proxy: {
    host: '127.0.0.1',
    port: 8080,
    username: 'user',     // Optional
    password: 'pass'      // Optional
  }
});

Custom Brave Path

const { browser, page } = await connect({
  customConfig: {
    bravePath: 'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
    userDataDir: './my-profile'
  }
});

Disable Blocker

const { browser, page } = await connect({
  enableBlocker: false,  // Disable all blocking
});

Custom Blocker Options

const { browser, page, blocker } = await connect({
  blockerOptions: {
    enableAdBlocking: true,
    enableStealth: true,
    enableCosmeticFiltering: true,
    enableRedirectBlocking: true,
    enableScriptlets: true,
    customFiltersPath: './my-filters.txt',
    enableFilterAutoUpdate: true,
  }
});

Real Cursor (Ghost-Cursor)

Built-in ghost-cursor for human-like mouse movements:

const { browser, page } = await connect();

// Human-like click
await page.realClick('#submit-button');

// Full cursor control
await page.realCursor.move('#element');
await page.realCursor.click('#button');

Turnstile Auto-Solver

Automatically solves Cloudflare Turnstile challenges:

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

await page.goto('https://site-with-turnstile.com');
// Turnstile is automatically solved!

Puppeteer-Extra Plugins

const clickAndWait = require('puppeteer-extra-plugin-click-and-wait')();

const { browser, page } = await connect({
  plugins: [clickAndWait]
});

Singleton Blocker Usage

The blocker is a singleton - only one instance is created and shared:

// From brave-real-blocker package
import { 
  getBraveBlockerSingleton, 
  initBraveBlockerSingleton,
  isBraveBlockerInitialized 
} from 'brave-real-blocker/singleton';

// Initialize once at startup
const blocker = await initBraveBlockerSingleton({
  enableAdBlocking: true,
  enableStealth: true,
});

// Get the same instance anywhere else
const sameBlocker = getBraveBlockerSingleton();
console.log(blocker === sameBlocker); // true

Commands

Root Level

Command	Description
npm start	Start unified server (MCP by default)
npm run dev	Start MCP server
npm run mcp	Start MCP server (alias)
npm run mcp:verbose	Start MCP server with tool details
npm run lsp	Start LSP server for IDE intelligence
npm run lsp:tcp	Start LSP server on TCP port 7777
npm run list	List all 23 optimized tools with categories
npm install	Install dependencies + auto-build workspaces + Brave check
npm test	Run all tests (CJS + ESM)
npm run cjs_test	Run CommonJS tests only
npm run esm_test	Run ESM tests only
npm run build	Build root package (pre-built lib/)
npm run build:all	Build all workspace packages (blocker, launcher, puppeteer-core)
npm run clean:all	Clean all workspace build outputs
npm run test:all	Run tests for all workspace packages
npm run update-deps	Manually check for dependency updates
npm run upstream-patch	Update to latest upstream (puppeteer-core, playwright-core)
npm run lint	Run linter

Note: npm install automatically runs npm run build:all to compile TypeScript packages (brave-real-blocker, brave-real-launcher) before the auto-update check. This ensures the browser tools work immediately after installation.

Workspace Scripts

Command	Description
node scripts/prepare-publish.js	Sync dependency versions before publish
node scripts/restore-workspace.js	Verify workspace linking
node scripts/version-bump.js patch	Increment all versions (patch/minor/major)

Package: brave-real-puppeteer-core

Command	Description
npm run patch-puppeteer	Apply stealth patches to puppeteer-core
npm run patch-playwright	Apply stealth patches to playwright-core
npm run patch-both	Apply patches to both engines
npm run setup-puppeteer	Full puppeteer setup with patches
npm run test-bot-detector	Run bot detection tests
npm run ai-agent	Run AI agent tests

Package: brave-real-launcher

Command	Description
npm run build	Build the launcher
npm run test:detection	Test Brave browser detection

Package: brave-real-blocker

Command	Description
npm run build	Build the blocker
npm run visual-test	Run visual blocking tests

Testing

# Run all 7 bot detector tests
npm test

# Run CJS tests only
npm run cjs_test

# Run ESM tests only
npm run esm_test

Test Coverage

All 7 bot detection tests pass:

Test	Description	Status
DrissionPage Detector	Chinese bot detector	✅ Pass
Sannysoft WebDriver	WebDriver detection	✅ Pass
Cloudflare WAF	Full page challenge	✅ Pass
Cloudflare Turnstile	CAPTCHA widget	✅ Pass
FingerprintJS	Browser fingerprinting	✅ Pass
Datadome	Anti-bot detection	✅ Pass
reCAPTCHA v3	Google score test (0.7+)	✅ Pass

Docker

Build and Run

# Build the image
docker build -t brave-real-browser-mcp-server .

# Run tests in container
docker run brave-real-browser-mcp-server

# Run with custom command
docker run brave-real-browser-mcp-server npm run esm_test

Docker Features

• Multi-stage build for smaller image size
• Node.js 20 LTS (pinned version)
• Non-root user for security
• Health check included
• Headless mode enabled by default

Project Structure

brave-real-browser-mcp-server/
├── src/
│   ├── shared/
│   │   └── tools.js              # Single source of truth (23 optimized tools)
│   ├── mcp/                      # MCP Server
│   │   ├── index.js              # Entry point with startup logs
│   │   ├── server.js             # MCP server with STDIO transport
│   │   ├── handlers.js           # 23 optimized tool implementations + decoders
│   │   └── tools.js              # Re-export from shared
│   ├── lsp/                      # LSP Server
│   │   ├── server.js             # LSP server for IDE intelligence
│   │   └── capabilities/         # Autocomplete, hover, diagnostics
│   └── ai/                       # AI Core Module
│       ├── core.js               # AI Core singleton
│       ├── element-finder.js     # Smart element finding
│       ├── selector-healer.js    # Auto-heal broken selectors
│       ├── page-analyzer.js      # Page analysis
│       └── action-parser.js      # Natural language parsing
├── lib/
│   ├── cjs/                      # CommonJS build
│   └── esm/                      # ESM build
├── packages/
│   ├── brave-real-blocker/       # Ad/Tracker blocker (singleton)
│   │   ├── src/
│   │   │   ├── brave-blocker.ts
│   │   │   ├── singleton.ts      # Singleton pattern
│   │   │   ├── stealth.ts
│   │   │   ├── cosmetic.ts
│   │   │   └── scriptlets.ts
│   │   └── package.json
│   ├── brave-real-launcher/      # Browser launcher
│   │   └── package.json
│   └── brave-real-puppeteer-core/  # Stealth patches
│       └── package.json
├── scripts/
│   ├── prepare-publish.js        # Sync versions before publish
│   ├── restore-workspace.js      # Verify workspace
│   └── version-bump.js           # Version management
├── .github/
│   └── workflows/
│       ├── auto-update-deps.yml      # Daily dependency updates
│       └── monorepo-publish.yml      # Auto-publish to NPM
├── test/
│   ├── cjs/                      # CJS tests
│   └── esm/                      # ESM tests
├── Dockerfile
├── typings.d.ts
└── package.json                  # Root with workspaces

Environment Variables

Create a .env file in your project root:

# Headless mode (true = headless, false = GUI)
HEADLESS=true

The library automatically reads .env files and respects the HEADLESS variable.

Re-exports

Access brave-real-launcher features directly:

const { 
  connect,
  launcher,      // brave-real-launcher module
  launch,        // Direct browser launch
  killAll,       // Kill all browsers
  getBravePath,  // Get Brave path
  DEFAULT_FLAGS  // Default browser flags
} = require('brave-real-browser-mcp-server');

TypeScript

Full TypeScript support with type definitions:

import { connect, Options, ConnectResult } from 'brave-real-browser-mcp-server';

const options: Options = {
  headless: false,
  turnstile: true,
  enableBlocker: true,
  blockerOptions: {
    enableAdBlocking: true,
    enableStealth: true,
  }
};

const { browser, page, blocker }: ConnectResult = await connect(options);

Real-World Examples

Example 1: Complete Movie Download Chain

Use Case: Extract download links from movie streaming sites with multi-layer redirects

// Step 1: Initialize browser with all protections
{
  "tool": "browser_init",
  "params": {
    "headless": false,
    "turnstile": true,
    "enableBlocker": true
  }
}

// Step 2: Navigate to movie page
{
  "tool": "navigate",
  "params": {
    "url": "https://moviesdrive.surf/movies/dhurandhar-2025/",
    "waitUntil": "networkidle2",
    "smartWait": true
  }
}

// Step 3: Find and click quality selector
{
  "tool": "click",
  "params": {
    "selector": "a[href*='hubcloud']",
    "humanLike": true,
    "aiHeal": true
  }
}

// Step 4: Wait for redirect chain to complete
{
  "tool": "wait",
  "params": {
    "type": "smart",
    "value": "2000",
    "aiOptimize": true
  }
}

// Step 5: Trace complete redirect chain
{
  "tool": "redirect_tracer",
  "params": {
    "url": "current",
    "followJS": true,
    "followMeta": true,
    "decodeURLs": true
  }
}

// Step 6: Extract obfuscated download links
{
  "tool": "extract_data",
  "params": {
    "type": "regex",
    "pattern": "https?://[^\"'<>\\s]+\\.(mkv|mp4|avi)",
    "autoDecode": true,
    "source": "all"
  }
}

// Step 7: Extract from nested iframes if present
{
  "tool": "media_extractor",
  "params": {
    "action": "extract",
    "types": ["download", "video"],
    "deep": true,
    "aiOptimize": true
  }
}

// Step 8: Download the file
{
  "tool": "file_downloader",
  "params": {
    "url": "extracted_download_link",
    "directory": "./downloads",
    "resume": true
  }
}

// Step 9: Cleanup
{
  "tool": "browser_close",
  "params": {
    "saveSession": false
  }
}

Example 2: TV Show Episode Batch Extraction

Use Case: Extract all episodes from a TV show season

// Navigate to TV show page
{
  "tool": "navigate",
  "params": { "url": "https://multimovies.gripe/tvshows/sacred-games/" }
}

// Extract all episode links
{
  "tool": "extract_data",
  "params": {
    "type": "structured",
    "selector": ".episode-item a",
    "extractAttributes": true
  }
}

// For each episode, extract streaming sources
{
  "tool": "media_extractor",
  "params": {
    "action": "batch_extract",
    "urls": ["episode1_url", "episode2_url", "..."],
    "types": ["hls", "dash", "download"],
    "deep": true
  }
}

// Get network recorded streams
{
  "tool": "network_recorder",
  "params": {
    "action": "get_media",
    "aiDetectStreams": true
  }
}

Example 3: Advanced Link Harvesting with Decoding

Use Case: Find hidden/obfuscated links on complex pages

// Navigate to target
{
  "tool": "navigate",
  "params": { "url": "https://example-site.com/protected-content/" }
}

// Harvest all links including hidden/encoded ones
{
  "tool": "link_harvester",
  "params": {
    "includeHidden": true,
    "autoDecode": true,
    "detectObfuscation": true,
    "searchIframes": true,
    "types": ["all"]
  }
}

// Decode any obfuscated links found
{
  "tool": "media_extractor",
  "params": {
    "action": "decode_url",
    "encodedData": "aHR0cHM6Ly9leGFtcGxlLmNvbQ==",
    "decoderType": "auto"
  }
}

Example 4: Form Automation with AI Detection

Use Case: Automatically fill and submit complex forms

// Navigate to form page
{
  "tool": "navigate",
  "params": { "url": "https://example.com/contact-form/" }
}

// AI-powered form detection and filling
{
  "tool": "form_automator",
  "params": {
    "data": {
      "name": "John Doe",
      "email": "[e-mail]",
      "message": "Hello, this is a test message",
      "country": "United States"
    },
    "aiMatch": true,
    "aiValidate": true,
    "humanLike": true,
    "captcha": true,
    "submit": true
  }
}

Example 5: Streaming Media Extraction

Use Case: Extract video streams from JWPlayer, VideoJS, custom players

// Navigate to video page
{
  "tool": "navigate",
  "params": { 
    "url": "https://multimovies.gripe/movies/movie-name/",
    "waitUntil": "networkidle0"
  }
}

// Start recording network
{
  "tool": "network_recorder",
  "params": { "action": "start", "aiDetectStreams": true }
}

// Extract all media types
{
  "tool": "media_extractor",
  "params": {
    "action": "extract",
    "types": ["hls", "dash", "video", "audio", "download"],
    "quality": "all",
    "deep": true
  }
}

// Get all recorded streams
{
  "tool": "network_recorder",
  "params": { 
    "action": "get_media",
    "filter": { "type": "m3u8" }
  }
}

// Control player if needed
{
  "tool": "media_extractor",
  "params": {
    "action": "player_control",
    "playerAction": "sources"
  }
}

FAQ

Why can't I pass reCAPTCHA v3?

When there's no Google session, reCAPTCHA identifies you as a bot. This is a known limitation - log into a Google account first.

page.setViewport not working?

Set defaultViewport in connectOption:

const { browser, page } = await connect({
  connectOption: { defaultViewport: null }
});

Mouse positions don't match?

This is automatically patched. Use page.realClick() for best results.

How to disable ad blocker?

const { browser, page } = await connect({
  enableBlocker: false
});

How to use custom filter lists?

const { browser, page } = await connect({
  blockerOptions: {
    customFiltersPath: './my-custom-filters.txt'
  }
});

How does the singleton blocker work?

The blocker uses a global Symbol-based singleton pattern. No matter how many times you import it, the same instance is shared across the entire Node.js process, preventing duplicate filter loading and saving memory.

How does npm workspaces linking work?

When packages are listed in the root package.json workspaces array, npm automatically creates symlinks to local packages instead of downloading from npm registry. This enables seamless local development.

Requirements

• Node.js >= 18.0.0
• Brave Browser (auto-installed if missing)
• Linux: xvfb package for headless mode

License

ISC - See LICENSE

Credits

• rebrowser - Runtime patches
• ghost-cursor - Human-like mouse movements
• brave-real-launcher - Brave Browser launcher
• @cliqz/adblocker-puppeteer - Ad blocking engine
• uBlock Origin - Filter lists

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Support

• GitHub Issues: Report bugs
• Documentation: README.md

Changelog

See Releases for version history and changes.