playwright-browser-mcp

A lightweight wrapper around @playwright/mcp that automatically starts a Chrome instance and connects it to a Playwright MCP server via the Chrome DevTools Protocol (CDP).

What it does

1. Launches Chrome using simple-browser
2. Auto-detects an available CDP port (starting from 9222)
3. Starts the @playwright/mcp server connected to that browser

This gives MCP clients (like Claude Code) full browser automation capabilities — clicking, typing, navigating, taking screenshots, and more — without manual browser setup.

Prerequisites

• Node.js and npm
• lsof (standard on macOS/Linux)

Quick start

With npx (no install)

npx --yes playwright-browser-mcp@latest

Installation

Claude Code

claude mcp add playwright -- npx --yes playwright-browser-mcp@latest

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["--yes", "playwright-browser-mcp@latest"]
    }
  }
}

Cursor

Go to Cursor Settings > MCP > Add new global MCP server and paste:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["--yes", "playwright-browser-mcp@latest"]
    }
  }
}

Codex CLI

codex mcp add playwright -- npx --yes playwright-browser-mcp@latest

Gemini CLI

gemini mcp add playwright npx --yes playwright-browser-mcp@latest

Or add to ~/.gemini/settings.json (user-level) or .gemini/settings.json (project-level):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["--yes", "playwright-browser-mcp@latest"]
    }
  }
}

CLI flags

| Flag | Default | Description | |------|---------|-------------| | --port <N> | Auto-detected from 9222 | Chrome CDP debugging port | | --output-dir <path> | .playwright-mcp/output | Directory for screenshots and artifacts | | --cdp-endpoint <url> | http://localhost:<port> | CDP endpoint URL (overrides port) |

All other arguments are passed through to @playwright/mcp.

Examples

# Use a specific port
./main.sh --port 9333

# Custom output directory
./main.sh --output-dir ./screenshots

# Connect to an existing Chrome instance
./main.sh --cdp-endpoint http://localhost:9222

How it works

• On first run, the wrapper finds an available port starting from 9222 and saves it to .playwright-mcp/port.txt for reuse across runs.
• Chrome is started via simple-browser (fetched automatically via npx).
• The @playwright/mcp server is then launched with --cdp-endpoint pointing at the running Chrome instance.

Port persistence

The chosen port is persisted to .playwright-mcp/port.txt. Delete this file to force re-detection:

rm .playwright-mcp/port.txt

License

MIT