Playwright MCP Docker

🚀 Playwright MCP Docker Environment

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 such as Cline or Cursor.

🚀 Quick Start

Prerequisites

• Docker
• Docker Compose

Setup

1. Clone the repository:

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

2. Create a .env file: Copy the example environment file:

   cp .env.sample .env
   

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

Run the Server

1. Build and start the container:

   docker-compose up --build -d
   

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

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

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

     {
       "mcpServers": {
         "playwright_sse": { // Server name can be anything
           "url": "http://localhost:8931/sse" // Match the port number in the .env file
         }
       }
     }
     

📚 Documentation

Other Information

• .env file: Used to configure environment variables such as port and mode settings.
• docker-compose.yml: Defines how to build and run the Docker services.
• Dockerfile: Specifies how to build the Docker image.
• entrypoint.sh: A script executed when the container starts.

Switch Modes

• Headless mode: Use HEADLESS=true to disable the GUI, suitable for automated tasks.
• Headed mode: Use HEADLESS=false to enable the GUI, suitable for scenarios that require a visual interface.

Notes

• When running in a WSLg environment, ensure that DISPLAY and other related environment variables are correctly set to display Linux GUI applications on Windows.
• If you encounter permission issues, check the Docker and WSLg configurations and ensure that the user has appropriate permissions.

Stop the Service

docker-compose down

By following the above steps, you can easily set up and run the Playwright MCP server. I hope these instructions are helpful to you!