playwright-sse-mcp-server

这是一个将 Playwright 作为 MCP（模型上下文协议）服务器提供的服务。通过使用此服务器，MCP 客户端可以利用 Playwright 的功能。

前提条件

• 已安装 Docker
• 已安装 docker-compose
• 已创建名为 mcp-network 的 Docker 网络

如果 mcp-network 不存在，可以使用以下命令创建：

docker network create mcp-network

设置和启动方法

1. 克隆或下载存储库
2. 在项目根目录中执行以下命令：

docker compose up --build

这将以默认端口 3002 启动服务器。启动完成后，将显示如下消息：

playwright-sse-mcp-server  | Server is running on port 3002

自定义端口的设置

如果要在默认端口（3002）以外的端口启动服务器，请设置环境变量 PORT：

PORT=4000 docker compose up --build

这将以指定的端口（本例中为 4000）启动服务器：

playwright-sse-mcp-server  | Server is running on port 4000

使用方法

从加入同一 mcp-network 的容器连接

从加入同一 mcp-network 的其他容器，可以使用以下 URL 连接到服务器（PORT 是服务器的启动端口）：

playwright-sse-mcp-server:${PORT}/sse

如果使用默认端口：

playwright-sse-mcp-server:3002/sse

这样就可以使用 Playwright 的 MCP 功能。

从主机连接

从主机，可以使用以下 URL 连接到服务器（PORT 是服务器的启动端口）：

localhost:${PORT}/sse

如果使用默认端口：

localhost:3002/sse

从 Roo Code 连接

MCP Servers -> 编辑 MCP 设置 -> 填写以下内容（PORT 是服务器的启动端口）：

{
  "mcpServers": {
    "playwright-sse-mcp-server-local": {
      "url": "http://localhost:${PORT}/sse"
    }
  }
}

如果使用默认端口：

{
  "mcpServers": {
    "playwright-sse-mcp-server-local": {
      "url": "http://localhost:3002/sse"
    }
  }
}

※截至 2025/03/27，Cline 不支持 SSE，因此无法使用。

从容器环境中的 Roo Code 连接

从同一 Docker Network 中运行的 Roo Code 容器，可以按如下方式进行 MCP 设置：

{
  "mcpServers": {
    "playwright-sse-mcp-server-local": {
      "url": "http://playwright-sse-mcp-server:3002/sse"
    }
  }
}

docker-compose.yml 设置示例：

services:
  # Roo Code 容器
  roo-code:
    # 略

networks:
  mcp-network:
    external: true

通过此设置，Roo Code 容器可以连接到 playwright-sse-mcp-server 容器，并使用浏览器操作功能。通过使用容器名称（playwright-sse-mcp-server）作为主机名，可以在 Docker Network 中进行名称解析。

从开发容器环境中的 Roo Code 连接（通过主机）

如果在开发容器中运行 Roo Code，并且不加入 mcp-network，而是通过主机连接到此 MCP 服务器，请按如下方式进行 MCP 设置。

Docker Desktop (Mac/Windows) 的情况:

{
  "mcpServers": {
    "playwright-sse-mcp-server-local": {
      "url": "http://host.docker.internal:<PORT>/sse"
    }
  }
}

Linux 的情况 (例如：使用桥接网关 IP):

{
  "mcpServers": {
    "playwright-sse-mcp-server-local": {
      "url": "http://172.17.0.1:<PORT>/sse"
    }
  }
}

注意:

• <PORT> 请替换为 MCP 服务器在主机上公开的端口号（默认：3002）。
• Linux 的情况下，请将 172.17.0.1 替换为实际的主机 IP 地址或 Docker 桥接网络的网关 IP 地址。 详情请参阅“从开发容器连接（通过主机）”部分。

从开发容器连接（通过主机）

如果需要从没有加入 mcp-network 的开发容器访问此 MCP 服务器（例如：由于与现有项目兼容性问题而难以更改网络），可以通过主机进行连接。

在这种方法中，指定从开发容器的角度来看的“主机”的 IP 地址或特殊的 DNS 名称，以及 MCP 服务器在主机上公开的端口（在 compose.yml 的 ports 中设置，默认为 3002）。

连接目标 URL:

http://<host_ip_or_dns_name>:<PORT>/sse

<PORT> 请替换为 MCP 服务器正在运行的端口号。

<host_ip_or_dns_name> 的确定方法:

• Docker Desktop (Mac/Windows): 可以使用特殊的 DNS 名称 host.docker.internal。
  • 例: http://host.docker.internal:3002/sse
• Linux:
  • 主机的 IP 地址: 使用分配给主机网络接口的 IP 地址（例如：使用 ifconfig 或 ip addr 命令查看）。
    • 例: http://192.168.1.10:3002/sse （IP 地址因环境而异）
  • Docker 桥接网络的网关: 可以使用 Docker 的默认桥接网络 (bridge) 的网关 IP 地址（通常为 172.17.0.1）。 可以使用 docker network inspect bridge 命令查看。
    • 例: http://172.17.0.1:3002/sse

注意点:

• 根据主机的防火墙设置，可能不允许开发容器访问主机的端口。
• 使用的端口号请在 docker compose ps 命令或 compose.yml 文件中确认。

方便的使用方法

每次都移动到项目目录并执行 docker compose 命令很麻烦。 使用以下方法，您可以从任何地方轻松启动和停止服务器。

使用 Shell 脚本的方法

此项目包含用于轻松启动、停止和显示服务器日志的 Shell 脚本。

1. 克隆或下载项目：

# 克隆到任意目录
git clone https://github.com/torohash/playwright-sse-mcp-server.git /path/to/installation

2. 将以下行添加到 .bashrc（或 .zshrc 等您使用的 shell 的配置文件）以加载 shell 脚本：

# Playwright MCP Server
export PLAYWRIGHT_MCP_HOME="/path/to/installation"
source "$PLAYWRIGHT_MCP_HOME/scripts/playwright-mcp.sh"

# 具体示例（使用绝对路径）
export PLAYWRIGHT_MCP_HOME="$HOME/mcps/playwright-sse-mcp-server"  # 请替换为实际路径
source "$PLAYWRIGHT_MCP_HOME/scripts/playwright-mcp.sh"

3. 重新启动 shell 或重新加载配置文件：

source ~/.bashrc

现在，您可以从任何地方使用以下命令：

基本使用方法

• playwright-mcp-start - 使用默认设置（端口 3002，无重启）启动服务器
• playwright-mcp-stop - 停止服务器
• playwright-mcp-logs - 显示服务器日志

使用持久模式

使用持久模式，服务器将在系统重启时自动启动：

playwright-mcp-start -p
# 或者
playwright-mcp-start --persistent

使用自定义端口

playwright-mcp-start -P 4000
# 或者
playwright-mcp-start --port 4000

组合使用持久模式和自定义端口

playwright-mcp-start -P 4000 -p
# 或者
playwright-mcp-start --port 4000 --persistent

指定特定的重启策略

playwright-mcp-start -r always
# 或者
playwright-mcp-start --restart always

显示帮助

playwright-mcp-start -h
# 或者
playwright-mcp-start --help

这种方法更易于使用，因为您可以使用标志选项灵活地更改设置。 此外，通过将 shell 脚本分离到单独的文件中，可以简化 .bashrc 文件并使其更易于管理。

Shell 脚本的自定义

Shell 脚本位于 scripts/playwright-mcp.sh 中。 您可以根据需要编辑此文件以进行自定义。

环境变量

Shell 脚本使用以下环境变量：

• PLAYWRIGHT_MCP_HOME: 项目的安装目录。 如果未设置，则从脚本的位置自动检测。

例如，您可以通过设置环境变量来指定自定义路径，如下所示：

export PLAYWRIGHT_MCP_HOME="/path/to/custom/installation"

注意事项

• 此服务器以 headless 模式运行 Playwright
• 服务器使用 SSE（Server-Sent Events）与 MCP 客户端通信