Playwright Mcp Wrapper

Reliable Playwright MCP servers for Docker/DevContainer development

The Problem This Solves

When developing inside Docker containers, you can't run browsers directly in the container. To use Playwright via MCP, you need to:

1. Run Playwright MCP servers on your host machine
2. Connect from your container to the host ports
3. Deal with frequent crashes of the MCP servers during development

This wrapper solves the crashing problem by using PM2 to automatically restart Playwright MCP servers when they crash, making container-based development reliable.

What It Does and How

What it does: This tool creates a reliable bridge between containerized development environments and browser automation by running persistent Playwright MCP servers on your host machine.

How it works:

1. Process Management: Uses PM2 to spawn and monitor 6 separate Playwright MCP server processes
2. Auto-Recovery: Monitors each server process and automatically restarts them when they crash or become unresponsive
3. Port Allocation: Assigns dedicated ports (8931-8936) to each browser type for consistent access
4. Container Bridge: Exposes servers on host network interfaces so containers can connect via host.docker.internal or host IP
5. Zero Configuration: Pre-configured browser settings, profiles, and output directories eliminate manual setup

Result: Developers get reliable, always-available browser automation from any container without dealing with crashes or complex networking setup.

Quick Start

npm install -g pm2 playwright  # Install dependencies
npm install                    # Install project
npm start                      # Start all browsers
npm stop                       # Stop all servers
npm test                       # Test all endpoints

🧪 MCP Client Configuration

Configure your project to use these Playwright MCP servers based on your environment:

📋 Local Development

Simple MCP server configuration, change the port and names as per your need.

{
  "mcpServers": {
    "playwright-chrome": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:8932/sse"
      }
    },
    "playwright-brave": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:8933/sse"
      }
    },
  }
}

🐳 DevContainer/Docker

For containers, replace localhost with:

• Docker: host.docker.internal:[PORT]/sse
• Alternative: Your host IP like 192.168.1.100:[PORT]/sse

🌐 All Available Browsers

Browser	Port	Profile Type
Chrome	8932	Default
Brave	8933	Default
Firefox	8934	Default
Chromium	8931	Default
WebKit	8935	Default
Comet	8936	Default
Brave Persistent	8941	Persistent
Comet Persistent	8942	Persistent

🔍 Testing Your Configuration

npm test   # Verify all servers are responding

This tests both MCP and SSE endpoints for all browsers and reports their status.

Customization

Browser Configuration Options

Each browser config file (configs/[browser].json) supports these key settings:

Isolated Mode (important for multiple instances):

• "isolated": true - Each server gets a separate browser profile (recommended for running multiple servers)
• "isolated": false - Servers share the same browser profile (may cause conflicts)

User Data Directory:

• "userDataDir": "./profiles/[browser]" - Where browser profile data is stored (cookies, sessions, etc.)

Launch Options:

• "headless": false - Show browser window (useful for debugging)
• "channel" - Browser channel (chrome, firefox, chromium)
• "executablePath" - Custom browser binary path (required for Brave, Comet)

Context Options:

• "viewport": { "width": 1920, "height": 1080 } - Default window size

Other Settings:

• "capabilities" - Features enabled (tabs, install, pdf, vision)
• "outputDir" - Where screenshots and downloads are saved

Example Configuration

{
  "browser": {
    "browserName": "chromium",
    "isolated": true,
    "userDataDir": "./profiles/chrome",
    "launchOptions": {
      "channel": "chrome",
      "headless": false,
      "args": ["--disable-blink-features=AutomationControlled"]
    }
  },
  "server": {
    "port": 8932,
    "host": "0.0.0.0"
  }
}

PM2 Settings

Edit ecosystem.config.js to adjust:

• Memory limits (default: 1GB per process)
• Restart policies (default: max 10 restarts)
• Logging configuration
• Environment variables

All servers auto-restart on crash with memory limits and structured logging.