<中文翻译> playwright-mcp 由于"playwright"是一个自动化测试工具的名字，在此情况下应保持其原始形式不变。因此，最终的翻译结果直接保留原名。

Playwright MCP

这是一个使用Playwright提供浏览器自动化能力的模型上下文协议（MCP）服务器。该服务器使大语言模型（LLMs）能够通过结构化的可访问性快照与网页进行交互，从而避免了需要截图或视觉调优模型的需求。

主要特性

• 快速且轻量级。使用Playwright的可访问性树，而不是基于像素的输入。
• 适合LLM。不需要视觉模型，完全基于结构化数据操作。
• 确定性的工具应用。避免了基于截图方法常见的模糊性。

要求

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

开始使用

首先，使用你的客户端安装Playwright MCP服务器。一个典型的配置如下所示：

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

<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=安装服务器&color=0098FF" alt="在VS Code中安装"> <img alt="在VS Code Insiders中安装" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=安装服务器&color=24bfa5">

<details><summary><b>在VS Code中安装</b></summary>

你也可以使用VS Code CLI来安装Playwright MCP服务器：

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

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

</details> <details> <summary><b>在Cursor中安装</b></summary>

前往Cursor设置 -> MCP -> 添加新的MCP服务器。按喜好命名，使用command类型并输入命令npx @playwright/mcp。你也可以通过点击编辑来验证配置或添加命令参数。

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

</details> <details> <summary><b>在Windsurf中安装</b></summary>

遵循Windsuff MCP 文档。使用以下配置：

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

</details> <details> <summary><b>在Claude Desktop中安装</b></summary>

遵循MCP安装指南，使用以下配置：

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

</details>

配置

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

> npx @playwright/mcp@latest --help
  --allowed-origins <origins>  允许浏览器请求的分号分隔的源列表。默认是允许所有。
  --blocked-origins <origins>  阻止浏览器请求的分号分隔的源列表。黑名单会在白名单之前被评估。如果没有使用白名单，不匹配黑名单的请求仍然会被允许。
  --block-service-workers      阻止服务工作者
  --browser <browser>          使用的浏览器或Chrome通道，可能值：chrome, firefox, webkit, msedge。
  --caps <caps>                启用的功能的逗号分隔列表，可能值：tabs, pdf, history, wait, files, install。默认是全部。
  --cdp-endpoint <endpoint>    连接的CDP端点。
  --config <path>              配置文件的路径。
  --device <device>            模拟的设备，例如："iPhone 15"
  --executable-path <path>     浏览器可执行文件的路径。
  --headless                   在无头模式下运行浏览器，默认是有界面的。
  --host <host>                绑定服务器的主机。默认是localhost。使用0.0.0.0绑定到所有接口。
  --ignore-https-errors        忽略HTTPS错误
  --isolated                   将浏览器配置保存在内存中，不保存到磁盘。
  --no-image-responses         不向客户端发送图像响应。
  --no-sandbox                 禁用通常会被沙箱的所有进程类型的沙箱。
  --output-dir <path>          输出文件目录的路径。
  --port <port>                监听SSE传输的端口。
  --proxy-bypass <bypass>      逗号分隔的绕过代理的域名，例如".com,chromium.org,.domain.com"
  --proxy-server <proxy>       指定代理服务器，例如"http://myproxy:3128"或"socks5://myproxy:8080"
  --save-trace                 是否将Playwright会话跟踪保存到输出目录。
  --storage-state <path>       孤立会话的存储状态文件路径。
  --user-agent <ua string>     指定用户代理字符串
  --user-data-dir <path>       用户数据目录的路径。如果未指定，将创建一个临时目录。
  --viewport-size <size>       指定浏览器视口大小（以像素为单位），例如"1280, 720"
  --vision                     运行使用截图的服务器（默认使用Aria快照）

用户配置文件

你可以像常规浏览器一样运行具有持久配置文件的Playwright MCP（默认），或者在测试会话中使用孤立的配置文件。

持久配置文件

所有登录信息都将存储在持久配置文件中，如果你希望清除离线状态，可以在会话之间删除它。 持久配置文件位于以下位置，并可以通过--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

孤立

在孤立模式下，每个会话都会在一个孤立的配置文件中启动。每次请求MCP关闭浏览器时，会话都会关闭并且该会话的所有存储状态都会丢失。你可以通过配置的contextOptions或--storage-state参数提供初始存储状态。了解更多关于存储状态的信息这里。

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

配置文件

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

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

<details> <summary>配置文件模式</summary>

{
  // 浏览器配置
  browser?: {
    // 使用的浏览器类型（chromium, firefox, 或 webkit）
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // 将浏览器配置保存在内存中，不保存到磁盘。
    isolated?: boolean;

    // 浏览器配置文件持久化的用户数据目录路径
    userDataDir?: string;

    // 浏览器启动选项（参见Playwright文档）
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // 浏览器通道（例如'chrome'）
      headless?: boolean;      // 在无头模式下运行
      executablePath?: string; // 浏览器可执行文件的路径
      // ... 其他Playwright启动选项
    };

    // 浏览器上下文选项
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... 其他Playwright上下文选项
    };

    // 连接到现有浏览器的CDP端点
    cdpEndpoint?: string;

    // 远程Playwright服务器端点
    remoteEndpoint?: string;
  },

  // 服务器配置
  server?: {
    port?: number;  // 监听的端口
    host?: string;  // 绑定的主机（默认：localhost）
  },

  // 启用的功能列表
  capabilities?: Array<
    'core' |    // 核心浏览器自动化
    'tabs' |    // 标签管理
    'pdf' |     // PDF生成
    'history' | // 浏览器历史
    'wait' |    // 等待工具
    'files' |   // 文件处理
    'install' | // 浏览器安装
    'testing'   // 测试
  >;

  // 启用视觉模式（截图而非可访问性快照）
  vision?: boolean;

  // 输出文件目录
  outputDir?: string;

  // 网络配置
  network?: {
    // 允许浏览器请求的源列表。默认是允许所有。同时匹配`allowedOrigins`和`blockedOrigins`的源将被阻止。
    allowedOrigins?: string[];

    // 阻止浏览器请求的源列表。同时匹配`allowedOrigins`和`blockedOrigins`的源将被阻止。
    blockedOrigins?: string[];
  };
 
  /**
   * 不向客户端发送图像响应。
   */
  noImageResponses?: boolean;
}

</details>

独立MCP服务器

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

npx @playwright/mcp@latest --port 8931

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

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

<details> <summary><b>Docker</b></summary>

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

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

你可以自己构建Docker镜像。

docker build -t mcr.microsoft.com/playwright/mcp .

</details> <details> <summary><b>编程使用</b></summary>

import http from 'http';

import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // 创建一个无头的Playwright MCP服务器，使用SSE传输
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // ...
});

</details>

工具

这些工具有两种模式可用：

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

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

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

视觉模式最适合那些能够基于提供的截图使用XY坐标空间与元素进行交互的计算机使用模型。

<details> <summary><b>交互</b></summary>

• browser_snapshot

  • 标题：页面快照
  • 描述：捕获当前页面的可访问性快照，这比截图更好
  • 参数：无
  • 只读：true

• browser_click

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

• browser_drag

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

• browser_hover

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

• browser_type

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

• browser_select_option

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

• browser_press_key

  • 标题：按键
  • 描述：按下键盘上的一个键
  • 参数：
    • key (string): 要按下的键名或要生成的字符，如ArrowLeft或a
  • 只读：false

• browser_wait_for

  • 标题：等待
  • 描述：等待文本出现或消失或指定时间过去
  • 参数：
    • time (number, 可选): 要等待的时间（秒）
    • text (string, 可选): 要等待的文本
    • textGone (string, 可选): 要等待消失的文本
  • 只读：true

• browser_file_upload

  • 标题：上传文件
  • 描述：上传一个或多个文件
  • 参数：
    • paths (array): 要上传的文件的绝对路径。可以是一个文件或多个文件。
  • 只读：false

• browser_handle_dialog

  • 标题：处理对话框
  • 描述：处理对话框
  • 参数：
    • accept (boolean): 是否接受对话框。
    • promptText (string, 可选): 提示对话框中的提示文本。
  • 只读：false

</details> <details> <summary><b>导航</b></summary>

• browser_navigate
  • 标题：导航到URL