Real Browser MCP

An MCP (Model Context Protocol) server that exposes a real browser (via puppeteer-real-browser) as tools for AI agents. The browser bypasses bot detection (Cloudflare, Turnstile, etc.) and behaves like a real user.

Features

• Full browser access: Navigate, search, click, type, run JavaScript
• Screenshots: Capture pages and save to DOWNLOADS_PATH
• Data collection: Extract content, run JS, save pages as HTML/MHTML
• Downloads: Files automatically saved to DOWNLOADS_PATH
• Multi-tab: List and switch between tabs

Requirements

• Node.js 18+
• Chrome/Chromium (used by puppeteer-real-browser)
• On Linux: sudo apt-get install xvfb

Installation

npm install

Configuration

Environment variables

DOWNLOADS_PATH – Where screenshots and downloads are saved. Default: ~/Downloads.

HEADLESS – true or 1 = headless (invisible). false or 0 = visible. Default: visible.

SHOW_BROWSER – 1/true/yes = visible browser. 0/false/no = headless. Use if HEADLESS is not respected by your MCP client (e.g. LM Studio).

Config file – If env vars are not passed by your MCP client, create real-browser-mcp.config.json in the project root with {"headless": false} to show the browser. The repo includes this file by default.

BROWSER_PROFILE_PATH – Path for Chrome's persistent profile (cookies, logins, localStorage). Default: ~/.real-browser-mcp/chrome-profile. Cookies and sessions persist between runs so you don't have to accept cookies every time.

ADBLOCK_ENABLED – Ghostery adblocker is enabled by default (blocks ads and trackers). Set to false or 0 to disable.

# Windows (PowerShell) - visible browser (default)
$env:DOWNLOADS_PATH = "C:\Users\YourName\Downloads"
# Do NOT set HEADLESS to see the website

# For headless (no window, e.g. CI):
$env:HEADLESS = "true"

# Linux/macOS - same logic
export DOWNLOADS_PATH="/home/user/Downloads"
# Omit HEADLESS = visible. export HEADLESS=true = headless

Agent Instructions (prompt.txt)

The prompt.txt file contains system instructions for the agent: when to use the browser proactively, how to research, and how to use memory tools. Add it to your agent's system prompt or Cursor rules so the agent knows how to use the browser tools without being asked.

Usage

Run the MCP server

npm start
# or
node src/index.js

Cursor / VS Code MCP config

Add to your MCP settings (e.g. ~/.cursor/mcp.json or Cursor Settings → MCP):

{
  "mcpServers": {
    "real-browser": {
      "command": "node",
      "args": ["E:\\MCP\\real-browser-mcp\\src\\index.js"],
      "env": {
        "DOWNLOADS_PATH": "C:\\Users\\YourName\\Downloads"
      }
    }
  }
}

Use an absolute path to the project. By default the browser is visible so you can see the website. Only add HEADLESS: "true" to env if you get "Connection closed" errors and have no display.

Available Tools

Tool	Description
browser_navigate	Navigate to a URL
browser_search	Search on Google, Bing, or DuckDuckGo
browser_screenshot	Take screenshot (saved to DOWNLOADS_PATH)
browser_evaluate	Run JavaScript in the page
browser_get_content	Get text or HTML from the page
browser_click	Click an element (uses human-like click)
browser_type	Type text into an input
browser_fill	Clear and fill an input
browser_save_page	Save page as HTML or MHTML
browser_wait	Wait for time or selector
browser_tabs	List or switch tabs
browser_close	Close the browser
get_downloads_path	Get the DOWNLOADS_PATH value

Example workflow

1. browser_search – Search for "latest AI news"
2. browser_get_content – Extract search results
3. browser_click – Click a result link
4. browser_screenshot – Capture the page
5. browser_save_page – Save as HTML for later
6. browser_close – Close when done

License

MIT