【技术文档摘要】：

Playwright Record MCP

Playwright Record MCP 是一个使用 Playwright 提供浏览器自动化能力的 Model Context Protocol (MCP) 服务器。此服务器增加了视频录制功能，用于记录浏览器交互。它使大型语言模型（LLMs）能够通过结构化的可访问性快照与网页进行交互，而无需截图或视觉模型。

主要特性

• 快速且轻量级：使用 Playwright 的可访问性树，而不是基于像素的输入。
• 适合 LLM：不需要视觉模型，完全基于结构化数据操作。
• 确定性的工具应用：避免了基于截图方法常见的模糊性。
• 视频录制：能够将浏览器交互录制为视频。

使用场景

• 网页导航和表单填写
• 结构化内容的数据提取
• 由 LLM 驱动的自动化测试
• 代理的一般用途浏览器交互
• 浏览器交互的录制和分析

安装

通过 NPM 安装

npm install @playwright/record-mcp

或者

npx @playwright/record-mcp

配置示例

NPX

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

在 VS Code 中安装

你可以使用 VS Code CLI 安装 Playwright Record MCP 服务器：

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

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

安装后，Playwright Record MCP 服务器将在 VS Code 中与你的 GitHub Copilot 代理一起可用。

命令行选项

Playwright Record 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：以无头模式运行浏览器（默认有界面）
• --port <port>：监听 SSE 传输的端口
• --user-data-dir <path>：用户数据目录的路径
• --vision：运行使用截图的服务器（默认使用 Aria 快照）
• --record：将浏览器交互录制为视频（新功能）
• --record-path <path>：保存录制文件的路径（默认：./recordings）
• --record-format <format>：录制格式，可能值：mp4, webm（默认：mp4）

用户数据目录

Playwright Record MCP 将使用位于以下位置的新配置文件启动浏览器：

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

所有登录信息都将存储在此配置文件中；你可以在会话之间删除它以清除离线状态。

运行无头浏览器（没有 GUI 的浏览器）

此模式适用于后台或批处理操作。

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

使用视频录制

要使用视频录制功能，请使用 --record 标志：

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

指定录制文件保存路径：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest",
        "--record",
        "--record-path", "./my-recordings"
      ]
    }
  }
}

指定录制格式：

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

在没有 DISPLAY 的 Linux 上运行有界面浏览器

当在没有显示的系统上或从 IDE 的工作进程运行有界面浏览器时，从具有 DISPLAY 的环境中运行 MCP 服务器，并传递 --port 标志以启用 SSE 传输。

npx @playwright/record-mcp@latest --port 8931

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

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

Docker

注意：当前 Docker 实现仅支持无头 Chromium。

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

构建 Docker 镜像：

docker build -t mcp/playwright-record .

工具模式

工具提供两种模式：

1. 快照模式（默认）：使用可访问性快照以获得更好的性能和可靠性
2. 视觉模式：使用截图进行基于视觉的交互

要使用视觉模式，请在启动服务器时添加 --vision 标志：

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

视觉模式最适合能够使用提供的截图基于 X-Y 坐标空间与元素进行交互的计算机使用模型。

使用自定义传输的编程用法

import http from 'http';

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

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

  // 创建一个带有 SSE 传输的无头 Playwright Record MCP 服务器
  const mcpServer = await createServer({ headless: true, record: true });
  const transport = new SSEServerTransport('/messages', res);
  await mcpServer.connect(transport);

  // ...
});

基于快照的交互

• browser_snapshot

  • 描述：捕获当前页面的可访问性快照，这比截图更好
  • 参数：无

• browser_click

  • 描述：在网页上执行点击
  • 参数：
    • element (字符串)：用于获取与元素交互权限的人类可读元素描述
    • ref (字符串)：来自页面快照的确切目标元素引用

• browser_drag

  • 描述：在两个元素之间执行拖放
  • 参数：
    • startElement (字符串)：用于获取与元素交互权限的人类可读源元素描述
    • startRef (字符串)：来自页面快照的确切源元素引用
    • endElement (字符串)：用于获取与元素交互权限的人类可读目标元素描述
    • endRef (字符串)：来自页面快照的确切目标元素引用

• browser_hover

  • 描述：悬停在页面上的元素上
  • 参数：
    • element (字符串)：用于获取与元素交互权限的人类可读元素描述
    • ref (字符串)：来自页面快照的确切目标元素引用

• browser_type

  • 描述：向可编辑元素输入文本
  • 参数：
    • element (字符串)：用于获取与元素交互权限的人类可读元素描述
    • ref (字符串)：来自页面快照的确切目标元素引用
    • text (字符串)：要输入到元素中的文本
    • submit (布尔值，可选)：是否提交输入的文本（在后面按下 Enter 键）
    • slowly (布尔值，可选)：是否一次输入一个字符。对于触发页面中的键处理程序很有用。默认情况下整个文本一次性填充。

视频录制工具（新功能）

• browser_record_start

  • 描述：开始录制浏览器交互
  • 参数：
    • path (字符串，可选)：保存录制文件的路径
    • format (字符串，可选)：录制格式（mp4 或 webm）

• browser_record_stop

  • 描述：停止并保存浏览器交互录制
  • 参数：无

• browser_record_pause

  • 描述：暂停当前录制
  • 参数：无

• browser_record_resume

  • 描述：恢复暂停的录制
  • 参数：无

• browser_record_list

  • 描述：返回当前录制文件列表
  • 参数：无

示例

开始和停止视频录制

// 开始视频录制
await mcpServer.invoke('browser_record_start', {
  path: './my-recordings/test-recording.mp4',
  format: 'mp4'
});

// 执行浏览器导航
await mcpServer.invoke('browser_navigate', {
  url: 'https://example.com'
});

// 与页面交互
const snapshot = await mcpServer.invoke('browser_snapshot');
// 在快照中查找元素...

// 停止视频录制
await mcpServer.invoke('browser_record_stop');

支持的浏览器

• Chrome
• Firefox
• WebKit
• Microsoft Edge

要求

• Node.js 18 或更高版本
• 必须安装所需的浏览器（或使用 browser_install 工具来安装）

许可证

Apache-2.0 许可证