Playwright MCP - 基于 Playwright 的模型上下文协议服务器

文章目录

- 一、项目概览
- - 相关资源
  - 核心功能
  - - 快照模式工具集
    - 视觉模式工具集
    - 浏览器管理
  - 核心特性
- 二、安装配置
- - VS Code 安装
  - 基础配置
  - 用户配置文件
  - 配置文件
- 三、运行
- - 命令行参数
  - 在 Linux 上运行
  - Docker
  - 编程式用法
  - 工具模式
  - 基于快照的交互操作
  - 基于视觉的交互操作
  - 标签页管理
  - 导航功能
  - 键盘操作
  - 控制台
  - 文件与媒体
  - 实用工具
  - 测试

一、项目概览

Playwright MCP 是一个基于 Playwright 的浏览器自动化服务，通过结构化可访问性快照（而非截图）实现大语言模型与网页的交互。

核心功能

快照模式工具集

browser_snapshot：获取可访问性快照
browser_click：基于元素引用点击
browser_type：文本输入（支持慢速输入模式）
browser_drag：拖拽操作

视觉模式工具集

browser_screen_capture：页面截图
browser_screen_click：坐标点击
browser_screen_type：键盘输入

浏览器管理

标签页管理（新建/切换/关闭）
导航控制（前进/后退）
控制台消息获取
PDF 生成功能

核心特性

1、高效轻量

基于 Playwright 可访问性树，非像素级输入
默认使用快照模式（Snapshot Mode），性能优于视觉模式

2、LLM 友好

纯结构化数据交互，无需视觉模型
确定性工具应用，避免基于截图方法的歧义问题

3、多模式支持

快照模式（默认）：browser_snapshot 等工具
视觉模式（需启用）：browser_screen_capture 等工具

二、安装配置

VS Code 安装

code –add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

基础配置

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

用户配置文件

Playwright MCP 将使用位于指定路径的新配置文件启动浏览器。所有登录信息都将存储在该配置文件中，如需清除离线状态，您可以在会话之间删除它。

Windows : %USERPROFILE%\\AppData\\Local\\ms-playwright\\mcp-{channel}-profile
macOS : ~/Library/Caches/ms-playwright/mcp-{channel}-profile
Linux : ~/.cache/ms-playwright/mcp-{channel}-profile

配置文件

Playwright MCP 服务器可以通过 JSON 配置文件进行配置。以下是完整的配置格式：

{
// Browser configuration
browser?: {
// Browser type to use (chromium, firefox, or webkit)
browserName?: 'chromium' | 'firefox' | 'webkit';

// Path to user data directory for browser profile persistence
userDataDir?: string;

// Browser launch options (see Playwright docs)
// @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
launchOptions?: {
channel?: string; // Browser channel (e.g. 'chrome')
headless?: boolean; // Run in headless mode
executablePath?: string; // Path to browser executable
// … other Playwright launch options
};

// Browser context options
// @see https://playwright.dev/docs/api/class-browser#browser-new-context
contextOptions?: {
viewport?: { width: number, height: number };
// … other Playwright context options
};

// CDP endpoint for connecting to existing browser
cdpEndpoint?: string;

// Remote Playwright server endpoint
remoteEndpoint?: string;
},

// Server configuration
server?: {
port?: number; // Port to listen on
host?: string; // Host to bind to (default: localhost)
},

// Enable vision mode (screenshots instead of accessibility snapshots)
vision?: boolean;

// Directory for output files
outputDir?: string;

// Tool-specific configurations
tools?: {
browser_take_screenshot?: {
// Disable base64-encoded image responses
omitBase64?: boolean;
}
}
}

您可以通过–config命令行选项指定配置文件：

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

三、运行

命令行参数

Playwright MCP 服务器支持以下命令行选项：

–browser <browser>：指定使用的浏览器或 Chrome 渠道。可选值包括：
- chrome、firefox、webkit、msedge
- Chrome 渠道：chrome-beta、chrome-canary、chrome-dev
- Edge 渠道：msedge-beta、msedge-canary、msedge-dev
- 默认值：chrome
–caps <caps>：启用以逗号分隔的功能列表，可选值：tabs、pdf、history、wait、files、install。默认启用全部功能。
–cdp-endpoint <endpoint>：指定连接的 CDP 端点
–executable-path <path>：指定浏览器可执行文件路径
–headless：以无头模式运行浏览器（默认显示界面）
–device：模拟移动设备
–user-data-dir <path>：指定用户数据目录路径
–port <port>：指定 SSE 传输监听的端口
–host <host>：指定服务器绑定的主机。默认为 localhost。使用 0.0.0.0 可绑定到所有接口。
–vision：运行使用截图的服务器（默认使用 Aria 快照）
–config <path>：指定配置文件路径

在 Linux 上运行

当在无显示器的系统上运行带界面的浏览器，或从 IDE 的工作进程运行时，请确保在包含 DISPLAY 变量的环境中启动 MCP 服务器，并通过 –port 参数启用 SSE 传输。

npx @playwright/mcp@latest –port 8931

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

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

Docker

注意：目前 Docker 实现仅支持无头模式（headless）的 Chromium 浏览器。

{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "–rm", "–init", "mcp/playwright"]
}
}
}

你可以自行构建 Docker 镜像。

docker build -t mcp/playwright .

编程式用法

import http from 'http';

import { createServer } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
// …

// Creates a headless Playwright MCP server with SSE transport
const mcpServer = await createServer({ headless: true });
const transport = new SSEServerTransport('/messages', res);
await mcpServer.connect(transport);

// …
});

工具模式

该工具提供两种使用模式：

1、快照模式（默认）：使用无障碍快照，提供更好的性能和可靠性 2、视觉模式：使用屏幕截图进行基于视觉的交互

如需使用视觉模式，在启动服务器时添加 –vision 参数：

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

Vision Mode 最适合能与元素通过 X Y 坐标空间

基于快照的交互操作

browser_snapshot
- 功能描述：捕获当前页面的无障碍访问快照（比普通截图更全面）
- 参数：无
browser_click
- 功能描述：在网页元素上执行点击操作
- 参数：
  - element (字符串)：人类可读的元素描述，用于获取交互权限
  - ref (字符串)：从页面快照中获取的精确目标元素引用
browser_drag
- 功能描述：在两个元素之间执行拖放操作
- 参数：
  - startElement (字符串)：人类可读的源元素描述，用于获取交互权限
  - startRef (字符串)：从页面快照中获取的精确源元素引用
  - endElement (字符串)：人类可读的目标元素描述，用于获取交互权限
  - endRef (字符串)：从页面快照中获取的精确目标元素引用
browser_hover
- 功能描述：将鼠标悬停在页面元素上
- 参数：
  - element (字符串)：人类可读的元素描述，用于获取交互权限
  - ref (字符串)：从页面快照中获取的精确目标元素引用
browser_type
- 功能描述：在可编辑元素中输入文本
- 参数：
  - element (字符串)：人类可读的元素描述，用于获取交互权限
  - ref (字符串)：从页面快照中获取的精确目标元素引用
  - text (字符串)：需要输入的文本内容
  - submit (布尔值，可选)：是否提交输入内容（输入后按回车）
  - slowly (布尔值，可选)：是否逐字符输入。适用于需要触发页面键盘监听器的场景，默认情况下会一次性填充所有文本
browser_select_option
- 功能描述：在下拉菜单中选择选项
- 参数：
  - element (字符串)：人类可读的元素描述，用于获取交互权限
  - ref (字符串)：从页面快照中获取的精确目标元素引用
  - values (数组)：需要在下拉菜单中选中的值数组，可以是单个值或多个值
browser_take_screenshot
- 功能描述：捕获当前页面截图（注意：不能基于截图执行操作，如需操作请使用 browser_snapshot）
- 参数：
  - raw (布尔值，可选)：是否返回未压缩的PNG格式图片，默认为false（返回JPEG格式）
  - element (字符串，可选)：人类可读的元素描述，用于获取截图权限。未提供时默认截取可视区域
  - ref (字符串，可选)：从页面快照中获取的精确目标元素引用。未提供时默认截取可视区域

基于视觉的交互操作

browser_screen_capture
- 功能描述：截取当前页面屏幕截图
- 参数：无
browser_screen_move_mouse
- 功能描述：将鼠标移动到指定位置
- 参数：
  - element (字符串)：用于获取元素交互权限的人类可读元素描述
  - x (数字)：X坐标
  - y (数字)：Y坐标
browser_screen_click
- 功能描述：点击鼠标左键
- 参数：
  - element (字符串)：用于获取元素交互权限的人类可读元素描述
  - x (数字)：X坐标
  - y (数字)：Y坐标
browser_screen_drag
- 功能描述：拖拽鼠标左键
- 参数：
  - element (字符串)：用于获取元素交互权限的人类可读元素描述
  - startX (数字)：起始X坐标
  - startY (数字)：起始Y坐标
  - endX (数字)：结束X坐标
  - endY (数字)：结束Y坐标
browser_screen_type
- 功能描述：输入文本
- 参数：
  - text (字符串)：需要输入到元素中的文本内容
  - submit (布尔值，可选)：是否提交已输入的文本（按回车键确认）

标签页管理

browser_tab_list
- 描述：列出浏览器标签页
- 参数：无
browser_tab_new
- 描述：打开新标签页
- 参数：
  - url (字符串，可选)：新标签页中要跳转的URL。如果未提供，新标签页将为空白页。
browser_tab_select
- 描述：通过索引选择标签页
- 参数：
  - index (数字)：要选择的标签页索引
browser_tab_close
- 描述：关闭标签页
- 参数：
  - index (数字，可选)：要关闭的标签页索引。如果未提供，则关闭当前标签页。

导航功能

browser_navigate
- 功能描述：跳转到指定URL
- 参数说明：
  - url (字符串类型)：需要跳转的目标网址
browser_navigate_back
- 功能描述：返回上一页面
- 参数说明：无
browser_navigate_forward
- 功能描述：前进到下一页面
- 参数说明：无

键盘操作

browser_press_key
- 功能描述：模拟键盘按键操作
- 参数说明：
  - key (字符串类型)：指定要按下的键名或生成的字符，例如 ArrowLeft 或 a

控制台

browser_console_messages
- 描述：返回所有控制台消息
- 参数：无

文件与媒体

browser_file_upload
- 描述：上传单个或多个文件
- 参数：
  - paths (数组)：待上传文件的绝对路径。可以是单个文件或多个文件。
browser_pdf_save
- 描述：将页面保存为PDF
- 参数：无

实用工具

browser_close
- 描述：关闭当前页面
- 参数：无
browser_wait
- 描述：等待指定的秒数
- 参数：
  - time (数字类型)：等待的秒数
browser_resize
- 描述：调整浏览器窗口大小
- 参数：
  - width (数字类型)：浏览器窗口的宽度
  - height (数字类型)：浏览器窗口的高度
browser_install
- 描述：安装配置文件中指定的浏览器。如果遇到浏览器未安装的错误提示，请调用此功能。
- 参数：无
browser_handle_dialog
- 描述：处理对话框
- 参数：
  - accept (布尔类型)：是否接受对话框。
  - promptText (字符串类型，可选)：提示对话框中的文本内容。

测试

browser_generate_playwright_test
- 功能描述：为指定场景生成 Playwright 测试用例
- 参数说明：
  - name (字符串类型)：测试名称
  - description (字符串类型)：测试描述
  - steps (数组类型)：测试步骤集合

伊织 xAI 2025-05-04（日）

Playwright MCP - 基于 Playwright 的模型上下文协议服务器

文章目录

一、项目概览

相关资源

核心功能

快照模式工具集

视觉模式工具集

浏览器管理

核心特性

二、安装配置

VS Code 安装

基础配置

用户配置文件

配置文件

三、运行

命令行参数

在 Linux 上运行

Docker

编程式用法

工具模式

基于快照的交互操作

基于视觉的交互操作

标签页管理

导航功能

键盘操作

控制台

文件与媒体

实用工具

测试

相关推荐

评论抢沙发

评论前必须登录！

热门标签

置顶推荐

热门文章

最新文章

文章目录

一、项目概览

相关资源

核心功能

快照模式工具集

视觉模式工具集

浏览器管理

核心特性

二、安装配置

VS Code 安装

基础配置

用户配置文件

配置文件

三、运行

命令行参数

在 Linux 上运行

Docker

编程式用法

工具模式

基于快照的交互操作

基于视觉的交互操作

标签页管理

导航功能

键盘操作

控制台

文件与媒体

实用工具

测试

相关推荐

评论 抢沙发

评论前必须登录！

热门标签

置顶推荐

热门文章

最新文章

评论抢沙发