Playwright记录上下文协议工具

Playwright MCP

一个使用 Playwright 提供浏览器自动化功能的 Model Context Protocol (MCP) 服务器。该服务器使 LLM 能够通过结构化的无障碍快照与网页进行交互，从而绕过了截图或视觉调优模型的需求。

主要特点

• 快速且轻量级：使用 Playwright 的无障碍树，而不是基于像素的输入。
• LLM 友好：不需要视觉模型，纯粹基于结构化数据操作。
• 确定性的工具应用：避免了基于截图方法常见的模糊性。

使用场景

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

示例配置

NPX

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

在 VS Code 中安装

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

或者，您也可以使用 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"]}'

安装完成后，您可以在 VS Code 中与您的 GitHub Copilot 代理一起使用 Playwright MCP 服务器。

命令行选项

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：以无头模式运行浏览器（默认为有头模式）
• --port <port>：用于 SSE 传输的监听端口
• --user-data-dir <path>：用户数据目录的路径
• --vision：运行使用截图的服务器（默认使用 Aria 快照）

用户数据目录

Playwright MCP 将使用位于

- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile` on Windows
- `~/Library/Caches/ms-playwright/mcp-chrome-profile` on macOS
- `~/.cache/ms-playwright/mcp-chrome-profile` on 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"
    }
  }
}

Docker

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

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

工具模式

工具提供两种模式：

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

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

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

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

使用Docker构建

您可以自行构建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);

  // ...
});

基于快照的交互

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

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

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

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

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

• browser_select_option
  • 描述：选择下拉菜单中的一个选项
  • 参数：
    • element (字符串)：用于获取与该元素交互权限的人类可读元素描述
    • ref (字符串)：来自页面快照的确切目标元素引用
    • values (数组)：要选择的下拉菜单中的值数组。可以是一个或多个值。

• browser_take_screenshot
  • 描述：截取当前页面的屏幕截图。你不能基于屏幕截图执行操作，请使用 browser_snapshot 进行操作。
  • 参数：
    • raw (布尔值, 可选)：是否以不压缩的形式返回（PNG 格式）。默认为 false，返回 JPEG 图像。
    • element (字符串, 可选)：用于获取对元素进行截图权限的人类可读元素描述。如果未提供，则截取视口的屏幕截图。如果提供了元素，则必须同时提供 ref。
    • ref (字符串, 可选)：来自页面快照的确切目标元素引用。如果未提供，则截取视口的屏幕截图。如果提供了 ref，则必须同时提供 element。

基于视觉的交互

• 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 (布尔值, 可选): 是否提交输入的文本（在输入后按 Enter 键）

标签页管理

• browser_tab_list
  • 描述: 列出浏览器标签页
  • 参数: 无

• browser_tab_new
  • 描述: 打开新标签页
  • 参数:
    • url (字符串, 可选): 新标签页要导航到的 URL。如果不提供，则新标签页将为空。

• browser_tab_select
  • 描述: 通过索引选择标签页
  • 参数:
    • index (数字): 要选择的标签页的索引

• browser_tab_close
  • 描述: 关闭标签页
  • 参数:
    • index (数字, 可选): 要关闭的标签页的索引。如果不提供，则关闭当前标签页。

导航

• browser_navigate
  • 描述: 导航到某个 URL
  • 参数:
    • 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 (number): 要等待的时间（以秒为单位）

• browser_resize
  • 描述：调整浏览器窗口大小
  • 参数：
    • width (number): 浏览器窗口的宽度
    • height (number): 浏览器窗口的高度

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

• browser_handle_dialog
  • 描述：处理对话框
  • 参数：
    • accept (boolean): 是否接受对话框。
    • promptText (string, 可选): 在提示对话框的情况下，提示文本的内容。