What is Playwright Mcp Docker

playwright-mcp-docker is a project that provides a Docker Compose environment to run the ‘@playwright/mcp’ server, enabling easy setup and management for clients like Cline or Cursor.

Use cases

Use cases include running automated tests for web applications, integrating with development tools like VSCode, and providing a server for real-time browser interactions.

How to use

To use playwright-mcp-docker, clone the repository, create and configure a .env file, and then build and start the Docker container using ‘docker-compose up --build -d’. Configure your MCP client to connect to the server using the specified URL.

Key features

Key features include easy Docker setup, support for headless and headed modes, customizable environment settings, and compatibility with various MCP clients.

Where to use

playwright-mcp-docker can be used in web development environments where automated testing and browser interactions are required, particularly with Playwright clients.

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):

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