Content
# 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
```
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
servers
Model Context Protocol Servers
Time
A Model Context Protocol server for time and timezone conversions.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
Sequential Thinking
A structured MCP server for dynamic problem-solving and reflective thinking.
git
A Model Context Protocol server for Git automation and interaction.