Playwright MCP Server with noVNC Display

A Docker Compose setup that runs the Microsoft Playwright MCP server with a virtual X11 display accessible via noVNC in your web browser.

Features

• Playwright MCP Server: Browser automation via Model Context Protocol (MCP)
• Headed Browser Mode: See the browser running in real-time
• noVNC Web Interface: View the browser display from any web browser
• Reusable Architecture: Persistent Playwright service that can be accessed via SSE or stdio
• stdio-to-SSE Proxy: Bridge between stdio-based MCP clients and the SSE endpoint

Quick Start

Using Docker Compose (Recommended)

1. Start the persistent Playwright + noVNC service:

docker compose up -d playwright-display

2. Access the services:
   • noVNC Web UI: http://localhost:6080/vnc.html
   • MCP SSE Endpoint: http://localhost:3080/sse

MCP Client Configuration

stdio transport (recommended):

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=playwright-network",
        "mcp-playwright-novnc:latest",
        "mcp-proxy",
        "http://playwright-display:3080/sse"
      ]
    }
  }
}

SSE transport (direct connection):

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:3080/sse"
    }
  }
}

Environment Variables

Docker Compose Configuration

The project includes a docker-compose.yml file with the persistent Playwright + noVNC service.

The Docker image also includes a mcp-proxy script that bridges stdio to SSE, allowing MCP clients using stdio transport to connect to the running Playwright service.

Proxy Usage: The mcp-proxy command accepts the SSE URL as a command-line argument:

mcp-proxy <SSE_URL>

You can also use the PLAYWRIGHT_SSE_URL environment variable as a fallback.

You can customize the environment variables in the compose file or via a .env file:

SCREEN_WIDTH=1920
SCREEN_HEIGHT=1080
SCREEN_DEPTH=24
MCP_BROWSER=chromium

Building Locally

# Build the Docker image
docker compose build

# Start the service
docker compose up -d

# View logs
docker compose logs -f playwright-display

Testing the Proxy

# Test the proxy connection
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  docker run --rm -i --network=playwright-network \
  mcp-playwright-novnc:latest mcp-proxy http://playwright-display:3080/sse

Architecture

The setup consists of a single Docker container running:

• Playwright MCP Server (port 3080): Accepts browser automation commands via SSE or stdio
• Chromium Browser: Runs on a virtual display (Xvfb)
• noVNC Web Interface (port 6080): View the browser in real-time via your web browser
• mcp-proxy: Bridges stdio-based MCP clients to the SSE endpoint

Available MCP Tools

The Playwright MCP server provides browser automation tools including:

• browser_navigate - Navigate to a URL
• browser_click - Click on elements
• browser_type - Type text into inputs
• browser_fill_form - Fill form fields
• browser_take_screenshot - Capture screenshots
• browser_snapshot - Capture accessibility snapshot
• browser_tabs - Manage browser tabs
• browser_close - Close the browser
• browser_evaluate - Evaluate JavaScript
• browser_console_messages - Get console messages
• And many more...

Using Pre-built Images

Pre-built images are available from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/xtr-dev/mcp-playwright-novnc:latest

Complete Setup Example

1. Create a docker-compose.yml file:

services:
  playwright-display:
    image: ghcr.io/xtr-dev/mcp-playwright-novnc:latest
    container_name: playwright-display
    ports:
      - "6080:6080"  # noVNC web interface
      - "3080:3080"  # MCP SSE endpoint
    environment:
      - SCREEN_WIDTH=1920
      - SCREEN_HEIGHT=1080
      - MCP_BROWSER=chromium
    networks:
      - playwright-network

networks:
  playwright-network:
    name: playwright-network

2. Start the service:

docker compose up -d

3. Configure your MCP client:

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=playwright-network",
        "ghcr.io/xtr-dev/mcp-playwright-novnc:latest",
        "mcp-proxy",
        "http://playwright-display:3080/sse"
      ]
    }
  }
}

4. Access the browser display:

Open http://localhost:6080 in your web browser to see the Playwright browser in action.

License

MIT License - see LICENSE file for details