Playwright MCP Server

剧作家 MCP

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

主要特点

• 快速且轻量。使用 Playwright 的可访问性树，而不是基于像素的输入。
• 适合法学硕士 (LLM) 。无需视觉模型，纯粹基于结构化数据运行。
• 确定性工具应用程序。避免了基于屏幕截图的方法中常见的歧义。

要求

• Node.js 18 或更高版本
• VS Code、Cursor、Windsurf、Claude Desktop 或任何其他 MCP 客户端

入门

首先，在您的客户端上安装 Playwright MCP 服务器。典型的配置如下：

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

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

前往Cursor Settings -> MCP -> Add new MCP Server 。根据个人喜好命名，使用command类型npx @playwright/mcp 。您也可以点击Edit来验证配置或添加命令参数。

按照 Windsuff MCP文档操作。使用以下配置：

按照 MCP 安装指南，使用以下配置：

配置

Playwright MCP 服务器支持以下参数。它们可以在上面的 JSON 配置中作为"args"列表的一部分提供：

用户个人资料

您可以像常规浏览器（默认）一样使用持久配置文件运行 Playwright MCP，或者在测试会话的隔离环境中运行。

持久配置文件

所有登录信息都将存储在持久配置文件中，如果您想清除离线状态，可以在会话之间删除它。持久配置文件位于以下位置，您可以使用--user-data-dir参数覆盖它。

孤立

在隔离模式下，每个会话都以隔离配置文件启动。每次您要求 MCP 关闭浏览器时，会话都会关闭，并且此会话的所有存储状态都会丢失。您可以通过配置的contextOptions或--storage-state参数向浏览器提供初始存储状态。点击此处了解更多关于存储状态的信息。

配置文件

Playwright MCP 服务器可以使用 JSON 配置文件进行配置。您可以使用--config命令行选项指定配置文件：

独立 MCP 服务器

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

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

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

您可以自己构建 Docker 镜像。

工具

该工具有两种模式：

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

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

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

• browser_snapshot
  • 标题：页面快照
  • 描述：捕获当前页面的可访问性快照，这比屏幕截图更好
  • 参数：无
  • 只读： true
• browser_click
  • 标题：点击
  • 描述：执行网页上的点击操作
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • ref （字符串）：来自页面快照的精确目标元素引用
  • 只读： false
• browser_drag
  • 标题：拖动鼠标
  • 描述：在两个元素之间执行拖放操作
  • 参数：
    • startElement （字符串）：用于获取与元素交互权限的人类可读的源元素描述
    • startRef （字符串）：来自页面快照的精确源元素引用
    • endElement （字符串）：用于获取与元素交互的权限的人类可读的目标元素描述
    • endRef （字符串）：来自页面快照的精确目标元素引用
  • 只读： false
• browser_hover
  • 标题：鼠标悬停
  • 描述：将鼠标悬停在页面上的元素上
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • ref （字符串）：来自页面快照的精确目标元素引用
  • 只读： true
• 浏览器类型
  • 标题：输入文本
  • 描述：在可编辑元素中输入文本
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • ref （字符串）：来自页面快照的精确目标元素引用
    • text （字符串）：输入到元素中的文本
    • submit （布尔值，可选）：是否提交输入的文本（按 Enter 键后）
    • slowly （布尔值，可选）：是否一次输入一个字符。用于触发页面中的按键处理程序。默认情况下，整个文本会一次性填充。
  • 只读： false
• browser_select_option
  • 标题：选择选项
  • 描述：在下拉菜单中选择一个选项
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • ref （字符串）：来自页面快照的精确目标元素引用
    • values （数组）：下拉菜单中要选择的值的数组。可以是单个值，也可以是多个值。
  • 只读： false
• browser_press_key
  • 标题：按下一个键
  • 描述：按下键盘上的一个键
  • 参数：
    • key （字符串）：要按下的键的名称或要生成的字符，例如ArrowLeft``a
  • 只读： false
• browser_wait_for
  • 标题：等待
  • 描述：等待文本出现或消失或等待指定的时间过去
  • 参数：
    • time （数字，可选）：等待的时间（秒）
    • text （字符串，可选）：等待的文本
    • textGone （字符串，可选）：等待消失的文本
  • 只读： true
• browser_file_upload
  • 标题：上传文件
  • 描述：上传一个或多个文件
  • 参数：
    • paths （数组）：要上传的文件的绝对路径。可以是单个文件，也可以是多个文件。
  • 只读： false
• browser_handle_dialog
  • 标题：处理对话
  • 描述：处理对话
  • 参数：
    • accept （布尔值）：是否接受对话。
    • promptText （字符串，可选）：提示对话框中的提示文本。
  • 只读： false
• browser_navigate
  • 标题：导航至 URL
  • 描述：导航至 URL
  • 参数：
    • url （字符串）：要导航到的 URL
  • 只读： false
• browser_navigate_back
  • 标题：回去
  • 描述：返回上一页
  • 参数：无
  • 只读： true
• browser_navigate_forward
  • 标题：前进
  • 描述：前进到下一页
  • 参数：无
  • 只读： true
• browser_take_screenshot
  • 标题：截取屏幕截图
  • 描述：截取当前页面的屏幕截图。您无法基于屏幕截图执行任何操作，请使用 browser_snapshot 执行操作。
  • 参数：
    • raw （布尔值，可选）：是否返回未压缩的图像（PNG 格式）。默认值为 false，即返回 JPEG 格式的图像。
    • filename （字符串，可选）：保存屏幕截图的文件名。如果未指定，则默认为page-{timestamp}.{png|jpeg} 。
    • element （字符串，可选）：用于获取元素截图权限的可读元素描述。若未提供，则截取视口范围的屏幕截图。若提供 element，则必须同时提供 ref。
    • ref （字符串，可选）：页面快照中目标元素的精确引用。若未提供，则截取视口的屏幕截图。若提供 ref，则必须同时提供元素。
  • 只读： true
• browser_pdf_save
  • 标题：另存为 PDF
  • 描述：将页面保存为 PDF
  • 参数：
    • filename （字符串，可选）：保存 PDF 文件的文件名。若未指定，则默认为page-{timestamp}.pdf 。
  • 只读： true
• browser_network_requests
  • 标题：列出网络请求
  • 描述：返回自加载页面以来的所有网络请求
  • 参数：无
  • 只读： true
• browser_console_messages
  • 标题：获取控制台消息
  • 描述：返回所有控制台消息
  • 参数：无
  • 只读： true
• 浏览器安装
  • 标题：安装配置中指定的浏览器
  • 描述：安装配置中指定的浏览器。如果出现浏览器未安装的错误，请调用此函数。
  • 参数：无
  • 只读： false
• browser_close
  • 标题：关闭浏览器
  • 描述：关闭页面
  • 参数：无
  • 只读： true
• browser_resize
  • 标题：调整浏览器窗口大小
  • 描述：调整浏览器窗口的大小
  • 参数：
    • width （数字）：浏览器窗口的宽度
    • height （数字）：浏览器窗口的高度
  • 只读： true
• browser_tab_list
  • 标题：列表选项卡
  • 描述：列出浏览器标签页
  • 参数：无
  • 只读： true
• browser_tab_new
  • 标题：打开新标签页
  • 描述：打开新标签页
  • 参数：
    • url （字符串，可选）：新标签页中导航到的 URL。如果不提供，新标签页将为空白。
  • 只读： true
• browser_tab_select
  • 标题：选择一个选项卡
  • 描述：通过索引选择选项卡
  • 参数：
    • index （数字）：要选择的选项卡的索引
  • 只读： true
• browser_tab_close
  • 标题：关闭标签页
  • 描述：关闭标签页
  • 参数：
    • index （数字，可选）：要关闭的标签页的索引。如果未提供，则关闭当前标签页。
  • 只读： false
• browser_generate_playwright_test
  • 标题：生成 Playwright 测试
  • 描述：为给定场景生成 Playwright 测试
  • 参数：
    • name （字符串）：测试的名称
    • description （字符串）：测试的描述
    • steps （数组）：测试的步骤
  • 只读： true
• browser_screen_capture
  • 标题：截取屏幕截图
  • 描述：截取当前页面的屏幕截图
  • 参数：无
  • 只读： true
• browser_screen_move_mouse
  • 标题：移动鼠标
  • 描述：移动鼠标到指定位置
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • x （数字）：X 坐标
    • y （数字）：Y 坐标
  • 只读： true
• browser_screen_click
  • 标题：点击
  • 描述：单击鼠标左键
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • x （数字）：X 坐标
    • y （数字）：Y 坐标
  • 只读： false
• browser_screen_drag
  • 标题：拖动鼠标
  • 描述：拖动鼠标左键
  • 参数：
    • element （字符串）：用于获取与元素交互的权限的人类可读的元素描述
    • startX （数字）：起始X坐标
    • startY （数字）：起始 Y 坐标
    • endX （数字）：结束X坐标
    • endY （数字）：结束 Y 坐标
  • 只读： false
• 浏览器屏幕类型
  • 标题：输入文本
  • 描述：输入文本
  • 参数：
    • text （字符串）：输入到元素中的文本
    • submit （布尔值，可选）：是否提交输入的文本（按 Enter 键后）
  • 只读： false
• browser_press_key
  • 标题：按下一个键
  • 描述：按下键盘上的一个键
  • 参数：
    • key （字符串）：要按下的键的名称或要生成的字符，例如ArrowLeft``a
  • 只读： false
• browser_wait_for
  • 标题：等待
  • 描述：等待文本出现或消失或等待指定的时间过去
  • 参数：
    • time （数字，可选）：等待的时间（秒）
    • text （字符串，可选）：等待的文本
    • textGone （字符串，可选）：等待消失的文本
  • 只读： true
• browser_file_upload
  • 标题：上传文件
  • 描述：上传一个或多个文件
  • 参数：
    • paths （数组）：要上传的文件的绝对路径。可以是单个文件，也可以是多个文件。
  • 只读： false
• browser_handle_dialog
  • 标题：处理对话
  • 描述：处理对话
  • 参数：
    • accept （布尔值）：是否接受对话。
    • promptText （字符串，可选）：提示对话框中的提示文本。
  • 只读： false