> [!IMPORTANT]
> This repository is no longer maintained.
>
> Please refer to the official Playwright MCP repository for its Docker image
> and setup instructions. Playwright CLI is also available as an alternative,
> particularly for coding-agent workflows:
>
> https://github.com/microsoft/playwright-mcp

# Playwright MCP Docker Environment

[日本語版はこちら (Japanese version here)](README_ja.md)

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:**
    ```bash
    git clone <repository-url>
    cd playwright-mcp-docker
    ```
2.  **Create `.env` file:**
    Copy the sample environment file:
    ```bash
    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:**
    ```bash
    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):
      ```json
      {
        "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

```bash
docker-compose down
```