一、简介

Playwright MCP 是一款基于模型上下文协议（MCP）的服务器，通过使用Playwright提供浏览器自动化功能。该服务器允许大型语言模型（LLM）通过结构化的无障碍性快照与网页互动，无需截图或调整视觉模型。

核心特性

• 快速且轻量：使用 Playwright 的无障碍树，而非基于像素的输入。
• 大型语言模型友好：无需视觉模型，完全在结构化数据上运行。
• 确定性的工具应用：避免了基于截图方法常见的模糊性。

二、安装配置

2.1 VSCode 中安装

可以使用 VS Code 命令行界面安装 Playwright MCP 服务器：

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

2.2 在 Cursor 中安装

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

2.3 配置参数说明

> npx @playwright/mcp@latest --help
  --allowed-origins <origins>  semicolon-separated list of origins to allow the
                               browser to request. Default is to allow all.
  --blocked-origins <origins>  semicolon-separated list of origins to block the
                               browser from requesting. Blocklist is evaluated
                               before allowlist. If used without the allowlist,
                               requests not matching the blocklist are still
                               allowed.
  --block-service-workers      block service workers
  --browser <browser>          browser or chrome channel to use, possible
                               values: chrome, firefox, webkit, msedge.
  --caps <caps>                comma-separated list of capabilities to enable,
                               possible values: tabs, pdf, history, wait, files,
                               install. Default is all.
  --cdp-endpoint <endpoint>    CDP endpoint to connect to.
  --config <path>              path to the configuration file.
  --device <device>            device to emulate, for example: "iPhone 15"
  --executable-path <path>     path to the browser executable.
  --headless                   run browser in headless mode, headed by default
  --host <host>                host to bind server to. Default is localhost. Use
                               0.0.0.0 to bind to all interfaces.
  --ignore-https-errors        ignore https errors
  --isolated                   keep the browser profile in memory, do not save
                               it to disk.
  --image-responses <mode>     whether to send image responses to the client.
                               Can be "allow", "omit", or "auto". Defaults to
                               "auto", which sends images if the client can
                               display them.
  --no-sandbox                 disable the sandbox for all process types that
                               are normally sandboxed.
  --output-dir <path>          path to the directory for output files.
  --port <port>                port to listen on for SSE transport.
  --proxy-bypass <bypass>      comma-separated domains to bypass proxy, for
                               example ".com,chromium.org,.domain.com"
  --proxy-server <proxy>       specify proxy server, for example
                               "http://myproxy:3128" or "socks5://myproxy:8080"
  --save-trace                 Whether to save the Playwright Trace of the
                               session into the output directory.
  --storage-state <path>       path to the storage state file for isolated
                               sessions.
  --user-agent <ua string>     specify user agent string
  --user-data-dir <path>       path to the user data directory. If not
                               specified, a temporary directory will be created.
  --viewport-size <size>       specify browser viewport size in pixels, for
                               example "1280, 720"
  --vision                     Run server that uses screenshots (Aria snapshots
                               are used by default)

三、用户配置文件

3.1 配置文件

Playwright MCP 服务器可以通过一个 JSON 格式的配置文件来进行设置。可以使用 --config 命令行选项来指定配置文件。

npx @playwright/mcp@latest --config path/to/config.json

3.2 持久配置文件

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

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-profile

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-profile

3.3 孤立模式

在孤立模式下，每次会话都是在孤立配置文件中启动的。每当要求MCP关闭浏览器时，会话即会结束，并且该会话所有的存储状态都会丢失。可以通过配置的 contextOptions 或通过 --storage-state 参数向浏览器提供初始存储状态。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

四、独立 MCP 服务器

当在无显示系统上运行带界面的浏览器或从 IDE 的工作进程中运行时，请在具有 DISPLAY 环境的上下文中启动 MCP 服务器，并传递 --port 参数来启用 SSE 传输。

npx @playwright/mcp@latest --port 8931

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

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

五、视觉模式

Playwright 提供两种模式：

1. 快照模式（默认）：使用无障碍快照以实现更佳的性能和可靠性
2. 视觉模式：使用截图进行基于视觉的交互

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

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

Vision Mode 在能够使用 X Y 坐标空间与元素交互的计算机使用模型中效果最佳，基于提供的屏幕截图。

六、交互 API

• browser_snapshot：页面快照
• browser_click：在网页上执行点击操作
• browser_drag：在两个元素之间执行拖放操作
• browser_hover：在页面上的元素上方悬停
• browser_type：在可编辑元素中输入文本
• browser_select_option：在下拉菜单中选择一个选项
• browser_press_key：在键盘上按下一个键
• browser_wait_for：等待文本出现或消失或指定的时间过去
• browser_file_upload：上传一个或多个文件
• browser_handle_dialog：处理对话框

七、导航

• browser_navigate：导航到一个 URL
• browser_navigate_back：后退到前一页
• browser_navigate_forward：前进到下一页

八、资源

• browser_take_screenshot：截取当前页面的屏幕截图
• browser_pdf_save：将页面保存为 PDF
• browser_network_requests：自页面加载以来返回所有网络请求
• browser_console_messages：返回所有控制台消息

九、工具

• browser_install：安装配置中指定的浏览器
• browser_close：关闭页面
• browser_resize：调整浏览器窗口的大小

十、标签

• browser_tab_list：列出浏览器标签
• browser_tab_new：打开一个新标签
• browser_tab_select：按索引选择标签
• browser_tab_close：关闭标签

十一、测试

• browser_generate_playwright_test：为给定场景生成 Playwright 测试

十二、视觉模式

• browser_screen_capture：截取当前页面的截图
• browser_screen_move_mouse：将鼠标移动到指定位置
• browser_screen_click：点击鼠标左键
• browser_screen_drag：拖拽鼠标左键
• browser_screen_type：在元素中输入文本
• browser_press_key：在键盘上按下一个键
• browser_wait_for：等待文本出现或消失或等待指定的时间过去
• browser_file_upload：上传一个或多个文件
• browser_handle_dialog：处理对话框