Playwright MCP Docker Environment

日本語版はこちら (Japanese version here)

This project provides a Docker Compose environment to run the @playwright/mcp server. It allows you to easily set up and manage the Playwright MCP server for use with clients like Cline or Cursor.

Prerequisites

• Docker
• Docker Compose

Setup

1. Clone the repository:

   git clone <repository-url>
   cd playwright-mcp-docker
   

2. Create .env file: Copy the sample environment file:

   cp .env.sample .env
   

3. Configure .env: Edit the .env file to adjust settings according to your environment and preferences:
   • MCP_HOST_PORT: The port on the host machine that the MCP server will be accessible through (default: 8931).
   • HEADLESS: Set to true for headless mode (no browser GUI) or false for headed mode (requires GUI setup). Default is true.
   • (Headed Mode Only) DISPLAY, WAYLAND_DISPLAY, XDG_RUNTIME_DIR: Environment variables needed for GUI applications in Linux environments (especially WSLg). Defaults are provided.
   • (Headed Mode Only) X11_HOST_PATH, WSLG_HOST_PATH: Host paths for X11 and WSLg sockets/directories. Defaults are provided. Adjust if your system configuration differs. For Windows Docker accessing WSL paths, use the \\wsl.localhost\DistroName\... format (see .env.sample).

Running the Server

1. Build and start the container:

   docker-compose up --build -d
   

   The --build flag is only needed the first time or when Dockerfile changes. The -d flag runs the container in detached mode (in the background).

2. Configure MCP Client (e.g., VSCode/Cline):

   • Add or enable an MCP server named playwright_sse (or any name you prefer).
   • Set the connection type to SSE.
   • Set the URL to http://localhost:<MCP_HOST_PORT>/sse (replace <MCP_HOST_PORT> with the value from your .env file, e.g., http://localhost:8931/sse).
   • Example client configuration (filename depends on the client):

   {
     "mcpServers": {
       "playwright_sse": { // Server name is arbitrary
         "url": "http://localhost:8931/sse" // Match the port number in .env
       }
     }
   }
   

Configuration Details

• .env file: Manages environment-specific settings like ports, headless mode, and paths for headed mode.
• docker-compose.yml: Defines the Docker service, reads variables from .env, sets up port mapping and volumes.
• Dockerfile: Defines the Docker image, installs @playwright/mcp and its dependencies (including Chrome).
• entrypoint.sh: Script that runs when the container starts, passing the correct arguments (--headless or --port) to the npx @playwright/mcp command based on the HEADLESS environment variable.

Switching Modes

• Headless Mode: Set HEADLESS=true in .env. Restart the container: docker-compose up -d.
• Headed Mode: Set HEADLESS=false in .env. Ensure your host environment (e.g., WSLg or X Server) is correctly set up. Restart the container: docker-compose up -d.

Headed Mode Notes (WSLg)

• If you are using WSLg on Windows, the default settings in docker-compose.yml and the WSL2-specific paths in .env.sample should generally work. Ensure the paths in your .env match your WSL distribution name if it's not Ubuntu.
• If you are not using WSLg (e.g., standard Linux desktop or macOS/Windows with a separate X Server), you will need to adjust the DISPLAY variable and potentially the volume mounts (X11_HOST_PATH) in your .env file according to your X Server setup.

Stopping the Server

docker-compose down