Real Browser MCP

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