Playwright MCP Docker 环境

April 10, 2025 · View on GitHub

本项目提供了一个用于运行 @playwright/mcp 服务器的 Docker Compose 环境。它可以让您轻松地设置和管理 Playwright MCP 服务器，以便与 Cline 或 Cursor 等客户端一起使用。

前置要求

克隆仓库：

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

创建 .env 文件： 复制示例环境文件：
```
cp .env.sample .env
```
配置 .env： 根据您的环境和偏好编辑 .env 文件以调整设置：
- MCP_HOST_PORT：MCP 服务器在主机上可访问的端口（默认：8931）。
- HEADLESS：设置为 true 表示无头模式（无浏览器 GUI）或 false 表示有头模式（需要 GUI 设置）。默认为 true。
- （仅限有头模式） DISPLAY、WAYLAND_DISPLAY、XDG_RUNTIME_DIR：Linux 环境中 GUI 应用程序所需的环境变量（特别是 WSLg）。已提供默认值。
- （仅限有头模式） X11_HOST_PATH、WSLG_HOST_PATH：X11 和 WSLg 套接字/目录的主机路径。已提供默认值。如果您的系统配置不同，请进行调整。对于访问 WSL 路径的 Windows Docker，请使用 \wsl.localhost\DistroName\... 格式（参见 .env.sample）。

构建并启动容器：
```
docker-compose up --build -d
```
仅在首次运行或 Dockerfile 发生更改时才需要 --build 标志。-d 标志使容器在后台运行。
配置 MCP 客户端（例如 VSCode/Cline）：
- 添加或启用名为 playwright_sse（或您喜欢的任何名称）的 MCP 服务器。
- 将连接类型设置为 SSE。
- 将 URL 设置为 http://localhost:<MCP_HOST_PORT>/sse（将 <MCP_HOST_PORT> 替换为您 .env 文件中的值，例如 http://localhost:8931/sse）。
- 客户端配置示例（文件名取决于客户端）：
```
{
  "mcpServers": {
    "playwright_sse": { // 服务器名称可任意设置
      "url": "http://localhost:8931/sse" // 端口号需与 .env 中的一致
    }
  }
}
```

.env 文件： 管理环境特定的设置，如端口、无头模式和有头模式的路径。
docker-compose.yml： 定义 Docker 服务，读取 .env 中的变量，设置端口映射和卷。
Dockerfile： 定义 Docker 镜像，安装 @playwright/mcp 及其依赖项（包括 Chrome）。
entrypoint.sh： 容器启动时运行的脚本，根据 HEADLESS 环境变量向 npx @playwright/mcp 命令传递正确的参数（--headless 或 --port）。

无头模式： 在 .env 中设置 HEADLESS=true。重启容器：docker-compose up -d。
有头模式： 在 .env 中设置 HEADLESS=false。确保您的主机环境（例如 WSLg 或 X Server）已正确设置。重启容器：docker-compose up -d。

如果您在 Windows 上使用 WSLg，docker-compose.yml 中的默认设置和 .env.sample 中的 WSL2 特定路径通常应该可以正常工作。如果您的 WSL 发行版名称不是 Ubuntu，请确保 .env 中的路径与您的发行版名称匹配。
如果您不使用 WSLg（例如，标准 Linux 桌面或带有单独 X Server 的 macOS/Windows），您需要根据您的 X Server 设置调整 .env 文件中的 DISPLAY 变量和可能的卷挂载（X11_HOST_PATH）。

docker-compose down