McpPlaywright

🚀 Playwright MCP

Playwright MCP 是一个模型上下文协议（MCP）服务器，它借助 Playwright 提供浏览器自动化功能。该服务器使大语言模型（LLMs）能够通过结构化的无障碍快照与网页进行交互，无需使用截图或经过视觉调整的模型。

✨ 主要特性

• 快速轻量：使用 Playwright 的无障碍树，而非基于像素的输入。
• 对大语言模型友好：无需视觉模型，完全基于结构化数据运行。
• 工具应用确定性高：避免了基于截图方法常见的歧义问题。

📦 安装指南

要求

• Node.js 18 或更高版本
• VS Code、Cursor、Windsurf、Claude Desktop、Goose 或其他 MCP 客户端

开始安装

首先，将 Playwright MCP 服务器与你的客户端一起安装。

标准配置适用于大多数工具：

{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}

不同客户端的安装方式如下：

claude mcp add playwright npx @playwright/mcp@latest

# 对于 VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

📚 详细文档

配置

Playwright MCP 服务器支持以下参数。这些参数可以在上述 JSON 配置中的 "args" 列表中提供：

> npx @playwright/mcp@latest --help
--allowed-origins   允许浏览器请求的源列表，用分号分隔。默认允许所有源。
--blocked-origins   阻止浏览器请求的源列表，用分号分隔。阻止列表在允许列表之前评估。如果仅使用阻止列表，不匹配阻止列表的请求仍然允许。
--block-service-workers      阻止服务工作者
--browser           要使用的浏览器或 Chrome 通道，可能的值：chrome、firefox、webkit、msedge。
--caps                 要启用的额外功能列表，用逗号分隔，可能的值：vision、pdf。
--cdp-endpoint     要连接的 CDP 端点。
--config               配置文件的路径。
--device             要模拟的设备，例如："iPhone 15"
--executable-path      浏览器可执行文件的路径。
--headless                   以无头模式运行浏览器，默认是有头模式
--host                 服务器绑定的主机。默认是 localhost。使用 0.0.0.0 绑定所有接口。
--ignore-https-errors        忽略 HTTPS 错误
--isolated                   将浏览器配置文件保存在内存中，不保存到磁盘。
--image-responses      是否向客户端发送图像响应。可以是 "allow" 或 "omit"，默认为 "allow"。
--no-sandbox                 禁用通常会沙盒化的所有进程类型的沙盒。
--output-dir           输出文件的目录路径。
--port                 SSE 传输监听的端口。
--proxy-bypass       要绕过代理的域名列表，用逗号分隔，例如 ".com,chromium.org,.domain.com"
--proxy-server        指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080"
--save-session               是否将 Playwright MCP 会话保存到输出目录。
--save-trace                 是否将会话的 Playwright 跟踪保存到输出目录。
--storage-state        隔离会话的存储状态文件的路径。
--user-agent      指定用户代理字符串
--user-data-dir        用户数据目录的路径。如果未指定，将创建一个临时目录。
--viewport-size        指定浏览器视口大小（像素），例如 "1280, 720"

用户配置文件

你可以像使用常规浏览器一样使用持久配置文件运行 Playwright MCP（默认方式），也可以在隔离上下文中进行测试会话。

持久配置文件

所有登录信息将存储在持久配置文件中，如果你想清除离线状态，可以在会话之间删除该文件。持久配置文件位于以下位置，你可以使用 --user-data-dir 参数覆盖它。

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile

隔离模式

在隔离模式下，每个会话都在隔离配置文件中启动。每次你要求 MCP 关闭浏览器时，会话将关闭，并且该会话的所有存储状态将丢失。你可以通过配置的 contextOptions 或 --storage-state 参数为浏览器提供初始存储状态。了解更多关于存储状态的信息 点击这里。

{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--isolated",
"--storage-state={path/to/storage.json}"
]
}
}
}

配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。你可以使用 --config 命令行选项指定配置文件：

npx @playwright/mcp@latest --config path/to/config.json

// 将浏览器配置文件保存在内存中，不保存到磁盘。
isolated?: boolean;

// 用于浏览器配置文件持久化的用户数据目录路径
userDataDir?: string;

// 浏览器启动选项（参见 Playwright 文档）
// @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
launchOptions?: {
channel?: string;        // 浏览器通道（例如 'chrome'）
headless?: boolean;      // 以无头模式运行
executablePath?: string; // 浏览器可执行文件的路径
// ... 其他 Playwright 启动选项
};

// 浏览器上下文选项
// @see https://playwright.dev/docs/api/class-browser#browser-new-context
contextOptions?: {
viewport?: { width: number, height: number };
// ... 其他 Playwright 上下文选项
};

// 用于连接现有浏览器的 CDP 端点
cdpEndpoint?: string;

// 远程 Playwright 服务器端点
remoteEndpoint?: string;

// 阻止浏览器请求的源列表。同时匹配 `allowedOrigins` 和 `blockedOrigins` 的源将被阻止。
blockedOrigins?: string[];

然后在 MCP 客户端配置中，将 url 设置为 HTTP 端点：

{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}

{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
}
}
}

docker build -t mcr.microsoft.com/playwright/mcp .