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

技术文档

文章目录

- 一、项目概览
- - 相关资源
  - 核心功能
  - - 快照模式工具集
    - 视觉模式工具集
    - 浏览器管理
  - 核心特性
- 二、安装配置
- - 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) }, // List of enabled capabilities capabilities?: Array< \'core\' | // Core browser automation \'tabs\' | // Tab management \'pdf\' | // PDF generation \'history\' | // Browser history \'wait\' | // Wait utilities \'files\' | // File handling \'install\' | // Browser installation \'testing\' // Testing >; // 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 ：指定使用的浏览器或 Chrome 渠道。可选值包括：
- chrome、firefox、webkit、msedge
- Chrome 渠道：chrome-beta、chrome-canary、chrome-dev
- Edge 渠道：msedge-beta、msedge-canary、msedge-dev
- 默认值：chrome
--caps ：启用以逗号分隔的功能列表，可选值：tabs、pdf、history、wait、files、install。默认启用全部功能。
--cdp-endpoint ：指定连接的 CDP 端点
--executable-path ：指定浏览器可执行文件路径
--headless：以无头模式运行浏览器（默认显示界面）
--device：模拟移动设备
--user-data-dir ：指定用户数据目录路径
--port ：指定 SSE 传输监听的端口
--host ：指定服务器绑定的主机。默认为 localhost。使用 0.0.0.0 可绑定到所有接口。
--vision：运行使用截图的服务器（默认使用 Aria 快照）
--config ：指定配置文件路径

在 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（日）

AI伪原创工具

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

文章目录

一、项目概览

相关资源

核心功能

快照模式工具集

视觉模式工具集

浏览器管理

核心特性

二、安装配置

VS Code 安装

基础配置

用户配置文件

配置文件

三、运行

命令行参数

在 Linux 上运行

Docker

编程式用法

工具模式

基于快照的交互操作

基于视觉的交互操作

标签页管理

导航功能

键盘操作

控制台

文件与媒体

实用工具

测试

公告

DeepSeek全套部署资料免费下载

免费可商用字体批量下载

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

文章目录

一、项目概览

相关资源

核心功能

快照模式工具集

视觉模式工具集

浏览器管理

核心特性

二、安装配置

VS Code 安装

基础配置

用户配置文件

配置文件

三、运行

命令行参数

在 Linux 上运行

Docker

编程式用法

工具模式

基于快照的交互操作

基于视觉的交互操作

标签页管理

导航功能

键盘操作

控制台

文件与媒体

实用工具

测试

相关问题

公告

DeepSeek全套部署资料免费下载

免费可商用字体批量下载