# Browser MCP Setup Guide

This project uses [Playwright MCP](https://playwright.dev/mcp) (`@playwright/mcp`) as the browser automation server — a flexible solution that supports **multiple browsers**, **existing profiles with logins**, and **configurable browser selection**.

## Prerequisites

Before Playwright MCP will work, the browser binaries must be downloaded. Run this once after install:

```bash
# Linux / WSL — also installs system dependencies (fonts, codecs, etc.)
npx playwright install --with-deps chromium

# macOS — system deps not needed
npx playwright install chromium
```

The `install.sh` script runs this automatically, but you can re-run it manually at any time. On WSL you will also need a display server (e.g. VcXsrv or WSLg) for headed mode; headless mode works without one.

## Quick Start

The default config (`playwright-mcp.json`) uses Playwright's bundled Chromium. Just start pi — the MCP server launches lazily on first browser tool use.

## How It Works

Playwright MCP is an MCP (Model Context Protocol) server that gives the AI agent browser automation capabilities: navigating pages, clicking elements, taking screenshots, filling forms, evaluating scripts, and more.

The `mcp.json` in the repo root tells pi to start the Playwright MCP server with our config:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config",
        "/path/to/playwright-mcp.json"
      ],
      "lifecycle": "lazy"
    }
  }
}
```

## Configuring Your Browser

### Option 1: Playwright bundled Chromium (current default)

Simplest setup — uses Playwright's own Chromium, no system browser needed:

```json
{
  "browser": {
    "browserName": "chromium"
  }
}
```

> **Note:** This runs an isolated Chromium without your existing logins/cookies.
> To reuse an existing browser profile, see the options below.

### Option 2: Google Chrome with existing profile

```json
{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
    },
    "userDataDir": "/Users/<you>/Library/Application Support/Google/Chrome/Default"
  }
}
```

### Option 3: Firefox

```json
{
  "browser": {
    "browserName": "firefox"
  }
}
```

> Note: Firefox doesn't support `userDataDir` in the same way. Use `--storage-state` for session persistence.

### Option 4: Isolated (no profile, fresh session every time)

For testing or when you don't want to use your real profile:

```json
{
  "browser": {
    "browserName": "chromium",
    "isolated": true
  }
}
```

Or simply pass `--isolated` as an arg in `mcp.json` instead of using a config file:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated"],
      "lifecycle": "lazy"
    }
  }
}
```

## Connecting to a Running Browser

Instead of launching a new browser, you can connect to one already running.

### By channel name

Enable remote debugging in your browser at `chrome://inspect/#remote-debugging`, then:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--cdp-endpoint=chrome"],
      "lifecycle": "lazy"
    }
  }
}
```

Supported channels: `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`.

### By CDP endpoint URL

Start your browser with `--remote-debugging-port=9222`, then:

```json
{
  "browser": {
    "cdpEndpoint": "http://localhost:9222"
  }
}
```

### Via Playwright Browser Extension

Install the [Playwright Extension](https://chromewebstore.google.com/detail/playwright-extension/mmlmfjhmonkocbjadbfplnigmagldckm) in Chrome/Edge to reuse your logged-in sessions, cookies, and installed extensions:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--extension"],
      "lifecycle": "lazy"
    }
  }
}
```

## Browser Paths by OS

### macOS

| Browser        | Executable Path                                                  |
| -------------- | ---------------------------------------------------------------- |
| Google Chrome  | `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`   |
| Brave          | `/Applications/Brave Browser.app/Contents/MacOS/Brave Browser`   |
| Microsoft Edge | `/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge` |
| Firefox        | `/Applications/Firefox.app/Contents/MacOS/firefox`               |

### macOS Profile Directories

| Browser | Profile Path                                                        |
| ------- | ------------------------------------------------------------------- |
| Chrome  | `~/Library/Application Support/Google/Chrome/Default`               |
| Brave   | `~/Library/Application Support/BraveSoftware/Brave-Browser/Default` |
| Edge    | `~/Library/Application Support/Microsoft Edge/Default`              |

### Linux

| Browser | Executable               | Profile Path                                    |
| ------- | ------------------------ | ----------------------------------------------- |
| Chrome  | `/usr/bin/google-chrome` | `~/.config/google-chrome/Default`               |
| Brave   | `/usr/bin/brave-browser` | `~/.config/BraveSoftware/Brave-Browser/Default` |
| Firefox | `/usr/bin/firefox`       | `~/.mozilla/firefox/<profile>`                  |

### Windows

| Browser | Executable                                                           | Profile Path                                                   |
| ------- | -------------------------------------------------------------------- | -------------------------------------------------------------- |
| Chrome  | `C:\Program Files\Google\Chrome\Application\chrome.exe`              | `%LOCALAPPDATA%\Google\Chrome\User Data\Default`               |
| Brave   | `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe` | `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Default` |

## Config File Reference

Full `playwright-mcp.json` schema:

```json
{
  "browser": {
    "browserName": "chromium | firefox | webkit",
    "isolated": false,
    "userDataDir": "/path/to/profile",
    "launchOptions": {
      "executablePath": "/path/to/browser",
      "headless": false
    },
    "cdpEndpoint": "http://localhost:9222",
    "initScript": ["./setup.js"],
    "initPage": ["./setup-page.ts"]
  },
  "capabilities": [
    "core",
    "core-navigation",
    "core-tabs",
    "core-input",
    "network",
    "storage",
    "testing",
    "vision",
    "pdf",
    "devtools"
  ],
  "network": {
    "allowedOrigins": ["*"],
    "blockedOrigins": []
  },
  "saveSession": false,
  "imageResponses": "allow"
}
```

## CLI Options

Common flags (can be used in `mcp.json` args instead of config file):

| Flag                       | Description                             |
| -------------------------- | --------------------------------------- |
| `--browser <name>`         | `chrome`, `firefox`, `webkit`, `msedge` |
| `--headless`               | Run without visible window              |
| `--isolated`               | Fresh in-memory profile                 |
| `--user-data-dir <path>`   | Custom profile directory                |
| `--executable-path <path>` | Custom browser binary                   |
| `--viewport-size <WxH>`    | e.g. `1280x720`                         |
| `--device <name>`          | Emulate device, e.g. `iPhone 15`        |
| `--extension`              | Connect via browser extension           |
| `--cdp-endpoint <url>`     | Connect to running browser              |
| `--config <path>`          | JSON config file                        |

## Troubleshooting

### "Browser is already running"

Playwright can't launch a new browser if the same profile directory is already locked by another browser instance. Either close the existing browser or use `--cdp-endpoint` to connect to it.

### Brave / other Chromium forks

Brave (and other Chromium forks like Edge, Vivaldi) work with `browserName: "chromium"` plus a custom `executablePath`. Set `userDataDir` to the browser's profile directory to reuse your logins, cookies, and extensions. See the path reference tables above for common locations.

### Multiple profiles

For Chrome/Brave/Edge with multiple profiles, change `Default` to `Profile 1`, `Profile 2`, etc. in the `userDataDir` path. Check your browser's profile directory to see available profiles.
