# dev-browser-mcp

MCP server for [SawyerHood/dev-browser](https://github.com/SawyerHood/dev-browser). Agents drive a persistent Chromium (or an already-running Chrome) with sandboxed JavaScript and a small set of structured tools.

Repository: [github.com/kamkozlowski/dev-browser-mcp](https://github.com/kamkozlowski/dev-browser-mcp)

Scripts run in QuickJS, not Node.js. Named pages persist across tool calls through the `dev-browser` daemon.

`dev-browser` (CLI + Playwright Chromium) is a dependency of this package. `npm install` downloads the CLI and installs Chromium. No global `dev-browser` install is required. Set `DEV_BROWSER_SKIP_CHROMIUM=1` to skip the Chromium download (for example when you only attach to an existing Chrome). `DEV_BROWSER_BIN` still overrides the bundled CLI.

## Install

Clone and build:

```bash
git clone https://github.com/kamkozlowski/dev-browser-mcp.git
cd dev-browser-mcp
npm install
npm run build
```

Or install from the GitHub tarball:

```bash
npm pack github:kamkozlowski/dev-browser-mcp
tar -xzf dev-browser-mcp-*.tgz
cd package
npm install
npm run build
```

## Cursor config

Add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`).

### Recommended: bootstrap from GitHub (cache under `~/.cache`)

No local clone needed. On first launch Cursor downloads the package, installs dependencies, builds, and starts the server:

```json
{
  "mcpServers": {
    "dev-browser": {
      "command": "bash",
      "args": [
        "/ABS/PATH/TO/dev-browser-mcp/scripts/bootstrap-mcp.sh"
      ],
      "env": {
        "DEV_BROWSER_HEADLESS": "true"
      }
    }
  }
}
```

If you do not keep a local clone, use this one-liner (same logic as `scripts/bootstrap-mcp.sh`):

```json
{
  "mcpServers": {
    "dev-browser": {
      "command": "bash",
      "args": [
        "-lc",
        "CACHE=\"${XDG_CACHE_HOME:-$HOME/.cache}/dev-browser-mcp\"; LOCK=\"$CACHE/.install.lock\"; PKG=\"$CACHE/package\"; ENTRY=\"$PKG/dist/index.js\"; mkdir -p \"$CACHE\"; install() { cd \"$CACHE\" && rm -rf package dev-browser-mcp-*.tgz && npm pack github:kamkozlowski/dev-browser-mcp >/dev/null && tar -xzf dev-browser-mcp-*.tgz && rm -f dev-browser-mcp-*.tgz && cd package && npm install && npm run build; }; if [ ! -f \"$ENTRY\" ]; then ( flock -n 9 || flock 9; [ -f \"$ENTRY\" ] || install ) 9>\"$LOCK\"; fi; [ -f \"$ENTRY\" ] || { echo \"Install failed; rm -rf $CACHE\" >&2; exit 1; }; cd \"$PKG\" && exec node dist/index.js"
      ],
      "env": {
        "DEV_BROWSER_HEADLESS": "true"
      }
    }
  }
}
```

If the server fails to start with `Cannot find module .../dist/index.js`, remove the broken cache and retry:

```bash
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/dev-browser-mcp"
```

To attach to your running Chrome instead of launching Chromium:

```json
{
  "mcpServers": {
    "dev-browser": {
      "command": "bash",
      "args": [
        "-lc",
        "CACHE=\"${XDG_CACHE_HOME:-$HOME/.cache}/dev-browser-mcp\"; LOCK=\"$CACHE/.install.lock\"; PKG=\"$CACHE/package\"; ENTRY=\"$PKG/dist/index.js\"; mkdir -p \"$CACHE\"; install() { cd \"$CACHE\" && rm -rf package dev-browser-mcp-*.tgz && npm pack github:kamkozlowski/dev-browser-mcp >/dev/null && tar -xzf dev-browser-mcp-*.tgz && rm -f dev-browser-mcp-*.tgz && cd package && npm install && npm run build; }; if [ ! -f \"$ENTRY\" ]; then ( flock -n 9 || flock 9; [ -f \"$ENTRY\" ] || install ) 9>\"$LOCK\"; fi; [ -f \"$ENTRY\" ] || { echo \"Install failed; rm -rf $CACHE\" >&2; exit 1; }; cd \"$PKG\" && exec node dist/index.js"
      ],
      "env": {
        "DEV_BROWSER_CONNECT": "auto",
        "DEV_BROWSER_SKIP_CHROMIUM": "true"
      }
    }
  }
}
```

Enable remote debugging in Chrome at `chrome://inspect/#remote-debugging`, or launch with `--remote-debugging-port=9222`.

### Local clone (simple)

After `npm install` and `npm run build` in your checkout:

```json
{
  "mcpServers": {
    "dev-browser": {
      "command": "node",
      "args": ["/ABS/PATH/TO/dev-browser-mcp/dist/index.js"],
      "env": {
        "DEV_BROWSER_HEADLESS": "true"
      }
    }
  }
}
```

### Local clone (self-bootstrapping, bash)

Cursor installs and builds on first launch if `dist/` is missing:

```json
{
  "mcpServers": {
    "dev-browser": {
      "command": "bash",
      "args": [
        "-lc",
        "REPO=\"/ABS/PATH/TO/dev-browser-mcp\"; if [ ! -f \"$REPO/dist/index.js\" ]; then cd \"$REPO\" && npm install && npm run build; fi; cd \"$REPO\" && exec node dist/index.js"
      ],
      "env": {
        "DEV_BROWSER_HEADLESS": "true"
      }
    }
  }
}
```

Replace `REPO` with your checkout path.

### Development (TypeScript, no build)

```json
{
  "mcpServers": {
    "dev-browser": {
      "command": "bash",
      "args": [
        "-lc",
        "REPO=\"/ABS/PATH/TO/dev-browser-mcp\"; cd \"$REPO\" && exec npx --yes tsx src/index.ts"
      ],
      "env": {
        "DEV_BROWSER_HEADLESS": "true"
      }
    }
  }
}
```

Replace `REPO` with your checkout path.

## Tools

| Tool | Purpose |
| --- | --- |
| `dev_browser_run` | **Main tool.** Execute a sandboxed Playwright script. |
| `dev_browser_list_pages` | List tabs: `{id, url, title, name}` |
| `dev_browser_page_open` | Get/create a named page (or attach by targetId) |
| `dev_browser_close_page` | Close a named page |
| `dev_browser_goto` | Navigate |
| `dev_browser_snapshot` | AI accessibility snapshot (`snapshotForAI`) |
| `dev_browser_screenshot` | PNG screenshot (also returned as an image) |
| `dev_browser_click` | Click by CSS selector or snapshot ref |
| `dev_browser_fill` | Fill an input |
| `dev_browser_type` | Type character by character |
| `dev_browser_evaluate` | `eval` JavaScript in the page |
| `dev_browser_wait_for_selector` | Wait for a selector |
| `dev_browser_status` | Daemon status |
| `dev_browser_browsers` | Managed browser instances |
| `dev_browser_stop` | Stop the daemon |
| `dev_browser_install` | Install Playwright Chromium |

Read `dev-browser://guide` for the full sandbox API, including `page.cua` (vision) and `page.domCua` (DOM ids).

## Environment

| Variable | Meaning |
| --- | --- |
| `DEV_BROWSER_BIN` | Override the bundled `dev-browser` CLI path |
| `DEV_BROWSER_SKIP_CHROMIUM` | `true` to skip postinstall / auto Chromium setup |
| `DEV_BROWSER_BROWSER` | Named daemon browser instance (default: `default`) |
| `DEV_BROWSER_HEADLESS` | `true` to launch Chromium without a window |
| `DEV_BROWSER_CONNECT` | `auto` / `true` to attach to Chrome, or a CDP URL |
| `DEV_BROWSER_IGNORE_HTTPS_ERRORS` | `true` for self-signed certs |
| `DEV_BROWSER_TIMEOUT` | Script timeout in seconds (default: `30`) |
| `DEV_BROWSER_IDLE_TIMEOUT` | Close idle launched browsers, e.g. `5m` |

Per-call `browser`, `connect`, `headless`, `ignoreHttpsErrors`, and `timeoutSeconds` override the environment.

## How it differs from Playwright MCP

[dev-browser](https://github.com/SawyerHood/dev-browser) is built around **one sandboxed script per decision**, not a long chain of atomic MCP calls. Use `dev_browser_run` for anything beyond a single goto/click/fill. Convenience tools exist so common inspect/act steps stay structured.

Unlike [benkraus/dev-browser-mcp](https://github.com/benkraus/dev-browser-mcp) (Chrome extension + CDP relay), this server wraps the official `dev-browser` CLI with its QuickJS sandbox and persistent daemon pages.

## Development

```bash
npm test
npm run typecheck
npm run build
```