playwright-mcp-wsl

Drop-in WSL-safe wrapper for @playwright/mcp. Prevents Chromium GPU crashes on Windows Subsystem for Linux.

The Problem

Running Claude Code (or any Playwright-based browser automation) on WSL2 with parallel browser sessions causes cascading crashes:

1. Chromium tries to allocate GPU memory through WSL's dxg bridge
2. Multiple browser instances exhaust GPU memory allocations
3. Chrome processes SEGFAULT (signal 11)
4. Crash cascade takes down the entire WSL instance

This is invisible to users — WSL just "crashes" or "freezes" with no clear error.

The Fix

This package wraps @playwright/mcp and automatically injects GPU-safe flags when running on WSL:

--disable-gpu
--disable-software-rasterizer
--disable-dev-shm-usage

On non-WSL systems, it passes through to @playwright/mcp unchanged. No performance impact — GPU acceleration is meaningless for headless browser automation.

Installation

Claude Code (recommended)

Add to your Claude Code settings (.claude/settings.json or global settings):

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

This replaces the default @playwright/mcp entry.

Manual / Other MCP Hosts

npx playwright-mcp-wsl@latest

All @playwright/mcp CLI flags are supported:

npx playwright-mcp-wsl@latest --headless --viewport-size 1440x900

Programmatic

const { createConnection } = require('playwright-mcp-wsl');
// Same API as @playwright/mcp, with WSL-safe defaults

How It Works

1. Detects WSL by reading /proc/version for Microsoft/WSL kernel strings
2. If WSL: sets PLAYWRIGHT_MCP_CONFIG to a bundled config that adds --disable-gpu and related flags to Chromium launch args
3. If not WSL: passes through to @playwright/mcp with zero modifications
4. If user has custom config: merges WSL-safe args into existing config (no overwrite)

What It Disables

| Flag | Why | |------|-----| | --disable-gpu | Prevents GPU memory allocation through the dxg bridge | | --disable-software-rasterizer | Prevents fallback software GPU that still uses dxg | | --disable-dev-shm-usage | Uses /tmp instead of /dev/shm (often undersized on WSL) |

What It Doesn't Affect

• Page rendering quality (identical for headless automation)
• JavaScript execution
• Network requests
• Screenshot quality
• DOM interaction
• Any Playwright MCP functionality

Compatibility

• WSL1 and WSL2
• Windows 10 and Windows 11
• Node.js 18+
• All @playwright/mcp versions >= 0.0.60
• Claude Code, Cursor, Windsurf, or any MCP-compatible host

Verifying It Works

When running on WSL, you'll see in stderr:

[playwright-mcp-wsl] Detected WSL2 + dxg bridge. Injecting GPU-safe config.

When running on non-WSL:

[playwright-mcp-wsl] Not running in WSL. Passing through to @playwright/mcp.

Background

This package was created after diagnosing cascading WSL crashes during parallel browser automation with Claude Code's PAI system. The root cause was Chromium's GPU memory allocation through WSL2's dxg (DirectX Graphics) bridge — a kernel-level GPU passthrough layer not designed for concurrent headless browser load.

Crash signature in dmesg:

misc dxg: dxgk: dxgvmb_send_create_allocation: send_create_allocation failed ffffffb5
misc dxg: dxgk: dxgkio_create_allocation: Ioctl failed: -75
chrome: potentially unexpected fatal signal 11
WSL (CaptureCrash): Capturing crash for pid: ..., executable: chrome, signal: 11

License

Apache-2.0 — same as Playwright.