Playwright MCP Server

官方

精选

Playwright MCP

一个模型上下文协议 (MCP) 服务器，它使用 Playwright 提供浏览器自动化功能。该服务器使 LLM 能够通过结构化的可访问性快照与网页交互，从而无需屏幕截图或视觉调整模型。

主要特性

• 快速且轻量: 使用 Playwright 的可访问性树，而不是基于像素的输入。
• 对 LLM 友好: 无需视觉模型，纯粹基于结构化数据运行。
• 确定性的工具应用: 避免了基于屏幕截图的方法常见的模糊性。

使用场景

• Web 导航和表单填写
• 从结构化内容中提取数据
• 由 LLM 驱动的自动化测试
• 用于代理的通用浏览器交互

示例配置

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

在 VS Code 中安装

使用以下按钮之一在 VS Code 中安装 Playwright MCP 服务器：

<!-- // Generate using?: const config = JSON.stringify({ name: 'playwright', command: 'npx', args: ["-y", "@playwright/mcp@latest"] }); const urlForWebsites = vscode:mcp/install?${encodeURIComponent(config)}; // Github markdown does not allow linking to vscode: directly, so you can use our redirect: const urlForGithub = https://insiders.vscode.dev/redirect?url=${encodeURIComponent(urlForWebsites)}; -->

<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">

或者，您可以使用 VS Code CLI 安装 Playwright MCP 服务器：

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

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

安装后，Playwright MCP 服务器将可用于 VS Code 中的 GitHub Copilot 代理。

CLI 选项

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。默认值为 all。
• --cdp-endpoint <endpoint>: 要连接的 CDP 端点
• --executable-path <path>: 浏览器可执行文件的路径
• --headless: 在无头模式下运行浏览器（默认情况下为有头模式）
• --port <port>: 用于监听 SSE 传输的端口
• --user-data-dir <path>: 用户数据目录的路径
• --vision: 运行使用屏幕截图的服务器（默认情况下使用 Aria 快照）

用户数据目录

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

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

所有登录信息都将存储在该配置文件中，如果您想清除离线状态，可以在会话之间删除它。

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

此模式对于后台或批量操作很有用。

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

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

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

npx @playwright/mcp@latest --port 8931

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

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

工具模式

这些工具在两种模式下可用：

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

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

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

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

通过自定义传输进行编程使用

import { createServer } from '@playwright/mcp';

// ...

const server = createServer({
  launchOptions: { headless: true }
});
transport = new SSEServerTransport("/messages", res);
server.connect(transport);

基于快照的交互

• browser_click

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

• browser_hover

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

• browser_drag

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

• browser_type

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

• browser_select_option

  • 描述：在下拉列表中选择一个选项
  • 参数：
    • element (string)：用于获取与元素交互的权限的人类可读的元素描述
    • ref (string)：页面快照中的确切目标元素引用
    • values (array)：要在下拉列表中选择的值的数组。这可以是单个值或多个值。

• browser_snapshot

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

• browser_take_screenshot

  • 描述：拍摄当前页面的屏幕截图。您无法根据屏幕截图执行操作，请使用 browser_snapshot 进行操作。
  • 参数：
    • raw (boolean, optional)：是否在不压缩的情况下返回（以 PNG 格式）。默认值为 false，它返回 JPEG 图像。

基于视觉的交互

• browser_screen_move_mouse

  • 描述：将鼠标移动到给定位置
  • 参数：
    • element (string)：用于获取与元素交互的权限的人类可读的元素描述
    • x (number)：X 坐标
    • y (number)：Y 坐标

• browser_screen_capture

  • 描述：拍摄当前页面的屏幕截图
  • 参数：无

• browser_screen_click

  • 描述：单击鼠标左键
  • 参数：
    • element (string)：用于获取与元素交互的权限的人类可读的元素描述
    • x (number)：X 坐标
    • y (number)：Y 坐标

• browser_screen_drag

  • 描述：拖动鼠标左键
  • 参数：
    • element (string)：用于获取与元素交互的权限的人类可读的元素描述
    • startX (number)：起始 X 坐标
    • startY (number)：起始 Y 坐标
    • endX (number)：结束 X 坐标
    • endY (number)：结束 Y 坐标

• browser_screen_type

  • 描述：键入文本
  • 参数：
    • text (string)：要键入的文本
    • submit (boolean, optional)：是否提交输入的文本（之后按 Enter）

• browser_press_key

  • 描述：按下键盘上的一个键
  • 参数：
    • key (string)：要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a

选项卡管理

• browser_tab_list

  • 描述：列出浏览器选项卡
  • 参数：无

• browser_tab_new

  • 描述：打开一个新选项卡
  • 参数：
    • url (string, optional)：要在新选项卡中导航到的 URL。如果未提供，则新选项卡将为空白。

• browser_tab_select

  • 描述：按索引选择一个选项卡
  • 参数：
    • index (number)：要选择的选项卡的索引

• browser_tab_close

  • 描述：关闭一个选项卡
  • 参数：
    • index (number, optional)：要关闭的选项卡的索引。如果未提供，则关闭当前选项卡。

导航

• browser_navigate

  • 描述：导航到 URL
  • 参数：
    • url (string)：要导航到的 URL

• browser_navigate_back

  • 描述：返回到上一页
  • 参数：无

• browser_navigate_forward

  • 描述：前进到下一页
  • 参数：无

键盘

• browser_press_key
  • 描述：按下键盘上的一个键
  • 参数：
    • key (string)：要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a

文件和媒体

• browser_file_upload

  • 描述：选择一个或多个要上传的文件
  • 参数：
    • paths (array)：要上传的文件的绝对路径。可以是单个文件或多个文件。

• browser_pdf_save

  • 描述：将页面另存为 PDF
  • 参数：无

实用工具

• browser_wait

  • 描述：等待指定的时间（以秒为单位）
  • 参数：
    • time (number)：要等待的时间（以秒为单位）（上限为 10 秒）

• browser_close

  • 描述：关闭页面
  • 参数：无

• browser_install

  • 描述：安装配置中指定的浏览器。如果您收到有关未安装浏览器的错误，请调用此命令。
  • 参数：无