dev-browser-mcp

MCP server for 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

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:

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:

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:

{
  "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):

{
  "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:

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

To attach to your running Chrome instead of launching Chromium:

{
  "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:

{
  "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:

{
  "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)

{
  "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 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 (Chrome extension + CDP relay), this server wraps the official dev-browser CLI with its QuickJS sandbox and persistent daemon pages.

Development

npm test
npm run typecheck
npm run build