Environment variables and MCP config

Playwriter is configured through CLI flags and environment variables. No config files needed.

Environment variables

Variable	Description	Default
`PLAYWRITER_HOST`	Remote relay server URL	`ws://localhost:19988`
`PLAYWRITER_TOKEN`	Auth token for remote connections	-
`PLAYWRITER_DIRECT`	CDP connection mode (see below)	-
`PLAYWRITER_API_KEY`	API key for cloud browsers	-

PLAYWRITER_DIRECT

Connect directly to Chrome's DevTools Protocol, bypassing the extension:

Value	Behavior
`1`	Auto-discover Chrome on port 9222
`ws://...` or `wss://...`	Explicit WebSocket endpoint
`host:port`	Resolves via HTTP probe to ws:// URL

12345# Auto-discover local Chrome
PLAYWRITER_DIRECT=1 playwriter session new

# Cloud browser provider
PLAYWRITER_DIRECT=wss://xxx.cdp.browser-use.com playwriter session new

PLAYWRITER_HOST and PLAYWRITER_TOKEN

For remote access, point to a relay server running on another machine:

123export PLAYWRITER_HOST=https://my-tunnel.traforo.dev
export PLAYWRITER_TOKEN=MY_SECRET
playwriter session new

CLI global flags

Flag	Description
`-s, --session <id>`	Session ID (required for `-e`, `-f`)
`-e <code>`	Execute JavaScript code inline
`-f <path>`	Execute JavaScript from a file
`--host <host>`	Remote relay server host
`--token <token>`	Auth token for remote connections
`--timeout <ms>`	Execution timeout (default: 10000)
`--patchright`	Use @playwriter/patchright-core for stealth

Session new flags

Flag	Description
`--browser <key>`	Browser type: extension ID, `headless`, `cloud`, `direct:port`
`--direct [endpoint]`	Direct CDP: auto-discover or explicit endpoint
`--proxy <region>`	Cloud proxy region (us, de, jp, etc.)
`--custom-proxy <url>`	Custom proxy (host:port or user:pass@host:port)
`--timeout <minutes>`	Cloud browser timeout (1-240, default 60)
`--disable-proxy-bandwidth-acceleration`	Load images/video with proxy

Browser start flags

Flag	Description
`--user-data-dir <dir>`	Persistent profile directory
`--headless`	Headless mode
`--headed`	Show browser window
`--disable-sandbox`	Disable Chrome sandbox

Serve flags

Flag	Description
`--host [host]`	Bind host (default: `0.0.0.0`)
`--token <token>`	Auth token (required for public hosts)
`--replace`	Kill existing server on the port

MCP configuration examples

Basic (extension mode)

12345678{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

Direct CDP

1234567891011{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_DIRECT": "1"
      }
    }
  }
}

Cloud browser provider

1234567891011{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_DIRECT": "wss://xxx.cdp.browser-use.com"
      }
    }
  }
}

Remote relay

123456789101112{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_HOST": "https://my-tunnel.traforo.dev",
        "PLAYWRITER_TOKEN": "MY_SECRET"
      }
    }
  }
}

Debugging configuration

Playwriter logs to files for debugging:

123456# Get log file paths
playwriter logfile
# typically: ~/.playwriter/relay-server.log

# CDP JSONL log for protocol debugging
jq -r '.direction + "\t" + (.message.method // "response")' ~/.playwriter/cdp.jsonl | uniq -c

Both files are recreated every time the relay server starts.