playwright-mcp

Playwright MCP

核心特性

• 快速且轻量：使用 Playwright 的无障碍树，而非基于像素的输入。

• LLM 友好：无需视觉模型，完全基于结构化数据操作。

• 确定性工具应用：避免基于截图方法常见的歧义问题。

使用场景

• 网页导航与表单填写

• 从结构化内容中提取数据

• 由 LLM 驱动的自动化测试

• 代理的通用浏览器交互

示例配置

目录

• 在 VS Code 中安装

• 命令行

• 用户配置文件

• 配置文件

• 在 Linux 上运行

• Docker

• 编程使用

• 工具模式

在 VS Code 中安装

命令行

• --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：以无头模式运行浏览器（默认以有头模式运行）

• --device：模拟移动设备

• --user-data-dir <path>：用户数据目录的路径

• --port <port>：SSE 传输监听的端口

• --host <host>：服务器绑定的主机。默认为 localhost。使用 0.0.0.0 绑定到所有接口。

• --vision：使用截图的服务器（默认使用 Aria 快照）

• --config <path>：配置文件的路径

用户配置文件

配置文件

在 Linux 上运行

Docker

编程使用

工具模式

1. 快照模式（默认）：使用无障碍快照，以提高性能和可靠性

2. 视觉模式：使用截图进行基于视觉的交互

基于快照的交互

• 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 (string)：用于获取与元素交互权限的人类可读元素描述
• ref (string)：页面快照中的精确目标元素引用
• text (string)：要输入到元素中的文本
• submit (boolean, 可选)：是否提交输入的文本（按下回车键）
• slowly (boolean, 可选)：是否逐个字符输入。对于触发页面中的按键处理程序非常有用。默认情况下，整个文本会一次性输入。

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

• browser_take_screenshot
• 描述：截取当前页面的截图。您不能基于截图执行操作，请使用 browser_snapshot 进行操作。
• 参数：
• raw (boolean, 可选)：是否返回未压缩的图像（PNG 格式）。默认为 false，返回 JPEG 图像。
• element (string, 可选)：用于获取截取元素权限的人类可读元素描述。如果未提供，则截取视口的截图。如果提供了 element，则必须提供 ref。
• ref (string, 可选)：页面快照中的精确目标元素引用。如果未提供，则截取视口的截图。如果提供了 ref，则必须提供 element。

基于视觉的交互

• browser_screen_capture
• 描述：截取当前页面的截图
• 参数：无

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

• 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, 可选)：是否提交输入的文本（按下回车键）

标签页管理

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

• browser_tab_new
• 描述：打开一个新标签页
• 参数：
• url (string, 可选)：新标签页中要导航到的 URL。如果未提供，新标签页将为空。

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

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

导航

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

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

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

键盘

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

控制台

• browser_console_messages
• 描述：返回所有控制台消息
• 参数：无

文件与媒体

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

• 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, 可选)：如果是提示对话框，则为提示的文本。