# Real Browser MCP

An MCP (Model Context Protocol) server that exposes a **real browser** (via [puppeteer-real-browser](https://github.com/ZFC-Digital/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

```bash
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.

```bash
# 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

```bash
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):

```json
{
  "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