微软Playwright MCP 服务器为LLM提供浏览器自动化能力

通过基于 Playwright 的 Claude MCP 服务器解锁大型语言模型的强大 Web 交互功能。这种创新的解决方案通过结构化的可访问性快照实现网页之间的LLMs无缝通信 - 无需屏幕截图或可视化模型 。

Repository  存储 库

https://github.com/microsoft/playwright-mcp

Homepage  主页

https://www.npmjs.com/package/@playwright/mcp

什么是 Playwright？

Playwright 是由 Microsoft 开发的开源浏览器自动化工具，使测试人员和开发人员能够跨多个浏览器和平台自动与 Web 应用程序进行交互。与传统的自动化工具不同，Playwright 专为现代 Web 应用程序而设计，支持动态内容、实时交互，甚至网络监控，帮助团队更快、更高效地测试应用程序。

在现代软件开发中，自动化浏览器测试已变得不可或缺，可确保 Web 应用程序在不同的浏览器和环境之间平稳运行。如果您使用过 Playwright，您就会了解它在自动化 Web 交互方面的强大功能。但是，当多个测试脚本、调试工具或自动化服务需要同时与同一个 Playwright 实例交互时，Playwright 多客户端协议 （MCP） 服务器将发挥作用。

Playwright 的核心功能

Multi-Browser Support  多浏览器支持

Playwright 无缝支持 Chromium、Firefox 和 WebKit，确保与主要浏览器的兼容性。这意味着可以在不同的浏览器上执行单个测试脚本，从而减少冗余工作并确保一致的用户体验。

Headless 和 Headed 执行模式

Playwright 可以在无头模式（无 UI）下运行以加速测试执行，使其成为 CI/CD 管道的理想选择。它还支持用于调试和交互式测试的 headed 模式，使开发人员能够直观地检查测试运行。

并行测试执行

Playwright 的最大优势之一是它能够同时执行多个测试。并行执行减少了整体测试运行时间，使其成为需要频繁快速测试的大型应用程序的理想解决方案。

高级调试工具

Playwright 包含内置工具，可显著简化调试失败测试的过程。它提供：

• • Trace Viewer– 测试执行的分步可视化表示
• • 视频录制 – 捕获测试运行以进行故障排除
• • 屏幕截图 – 帮助检测 UI 不一致

强大的 Web 交互 API

Playwright 支持广泛的用户交互，包括：

• • 单击按钮、填写表单和滚动
• • 捕获网络请求和响应
• • 处理身份验证流和 Cookie
• • 自动上传和下载文件

Playwright MCP 服务器

Playwright MCP 服务器是基于 Playwright 的 MCP 服务器，使测试人员和开发人员能够跨多个浏览器和平台自动与 Web 应用程序进行交互。此服务器允许大型语言模型 （）LLMs 通过结构化的辅助功能快照与 Web 页面进行交互，而无需依赖屏幕截图或视觉调整的模型。它提供以下核心功能：

• •通过浏览器自动化启用 LLMs：通过 MCP 连接 LLMs，允许 AI 直接操做网页。与 Claude、GPT-4o 和 DeepSeek 等大型语言模型兼容。
• •支持 Web 页面交互 ：支持常见的 Web 作，包括单击按钮、填写表单和滚动页面。
• •捕获 Web 屏幕截图 ：通过 Playwright MCP 服务器获取网页的屏幕截图，以分析当前的 UI 和内容。
• •执行 JavaScript 代码 ：在浏览器环境中运行 JavaScript，以便与网页进行更复杂的交互。
• •集成便利工具 ：支持 Smithery 和 mcp-get 等工具，以简化安装和配置。

非常适合自动化测试、数据抓取、SEO 竞争对手分析、AI 智能代理等。如果您希望 AI 更智能地处理 Web 任务或需要高效的自动化工具，请尝试 Playwright MCP Server。

在 Cursor 中安装

在 光标设置 中，切换到 MCP 选项卡，单击右上角的  添加新的全局 MCP 服务器  按钮，然后输入以下配置：

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

如果您不想全局启用它，请将上述配置添加到项目根目录中的 .cursor/mcp.json 文件中。

⚠️ 注意：官方文档建议使用 npx @playwright/mcp@latest 命令，但它在配置过程中可能会导致错误：

$ npx @playwright/mcp@latest


node:internal/modules/cjs/loader:646      throw e;      ^
Error: Cannot find module '/Users/cnych/.npm/_npx/9833c18b2d85bc59/node_modules/yaml/dist/index.js'    at createEsmNotFoundErr (node:internal/modules/cjs/loader:1285:15)    at finalizeEsmResolution (node:internal/modules/cjs/loader:1273:15)    at resolveExports (node:internal/modules/cjs/loader:639:14)    at Module._findPath (node:internal/modules/cjs/loader:747:31)    at Module._resolveFilename (node:internal/modules/cjs/loader:1234:27)    at Module._load (node:internal/modules/cjs/loader:1074:27)    at TracingChannel.traceSync (node:diagnostics_channel:315:14)    at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)    at Module.require (node:internal/modules/cjs/loader:1339:12)    at require (node:internal/modules/helpers:135:16) {  code: 'MODULE_NOT_FOUND',  path: '/Users/cnych/.npm/_npx/9833c18b2d85bc59/node_modules/yaml/package.json'}

将 npx @playwright/mcp@latest 替换为 npx @playwright/mcp。

配置后，您应该会在 Cursor Settings 的 MCP 选项卡中看到 Playwright MCP 服务器已成功配置：

VS Code 安装

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

For VS Code Insiders

安装后，Playwright MCP 服务器将立即可供 VS Code 中的 GitHub Copilot 代理使用。

高级配置

浏览器选项

你可以向 args 添加参数来自定义浏览器：

• •--browser <browser>: Options:
  --browser <browser>：选项：
• • 标准浏览器：chrome、firefox、webkit、msedge
• • Chrome 变体：chrome-beta、chrome-canary、chrome-dev
• • Edge 变体：msedge-beta、msedge-canary、msedge-dev
• •  默认值：chrome
• •--cdp-endpoint <endpoint>：连接到现有的 Chrome DevTools 协议端点
• •--executable-path <path>：指定自定义浏览器可执行文件路径
• •--headless：以 headless 模式运行（默认为 headed）
• •--port <port>：设置 SSE 传输侦听端口
• •--user-data-dir <path>： 自定义用户数据目录
• •--vision：开启截图交互模式

配置文件管理

Playwright MCP 在以下位置创建专用的浏览器配置文件：

• • Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile
• • macOS: ~/Library/Caches/ms-playwright/mcp-chrome-profile
• • Linux: ~/.cache/ms-playwright/mcp-chrome-profile

在会话之间删除这些目录将清除浏览状态。

Operation Modes

Headless Operation (Recommended for Automation)

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

Headed Operation on Headless Systems

对于无头或 IDE 工作进程的 Linux 系统，您可以使用 SSE 传输启动服务器。首先，使用以下命令启动服务器：

npx @playwright/mcp --port 8931

然后配置 MCP 客户端：

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

交互模式

服务器运行并连接到代理后，代理可以调用 MCP 提供的特定工具来控制浏览器。可用工具取决于服务器是在快照模式还是图像模式下运行。

快照模式（推荐）

这是默认模式，使用辅助功能快照来实现最佳性能和可靠性。提供的 MCP 工具主要使用辅助功能树进行作。典型的工作流程包括：

1. 1. 使用 browser_snapshot 获取辅助功能树的当前状态。
2. 2. 代理分析快照（结构化文本/JSON）以了解页面内容并识别目标元素。快照中的每个交互式元素通常都有一个唯一的 ref （引用标识符）。
3. 3. 代理调用 browser_click 或 browser_type 等交互工具，提供目标元素的 ref。

Playwright MCP 提供了一套用于浏览器自动化的工具。以下是所有可用的工具：

• •browser_navigate：导航到 URL
• • 参数：
• • url (string): The URL to navigate to
  url （string）：要导航到的 URL
• •browser_go_back：返回上一页
• • Parameters: None  参数： 无
• •browser_go_forward：前进到下一页
• • Parameters: None  参数： 无
• •browser_click：点击元素
• • 参数：
  element （string）：要单击的元素的说明
  ref （string）：页面快照中的精确目标元素引用
• •browser_hover：将鼠标悬停在元素上
• • 参数：
  element （string）：要悬停的元素的描述
  ref （string）：页面快照中的精确目标元素引用

-browser_drag：拖放元素
- 参数：
startElement （string）：要拖动的元素的描述
startRef （string）：页面快照中的精确源元素引用
endElement （string）：要放置到的目标元素的描述
endRef （string）：页面快照中的精确目标元素引用

• • **browser_type：输入文本（可选提交）
• • 参数：
• • element （string）：要输入文本的元素的描述
• • ref （string）：页面快照中的精确目标元素引用
• • text （string）：要输入的文本
• • submit （boolean）：是否提交输入文本（之后按 Enter）
• • **browser_select_option：选择下拉选项
• • 参数：
  element （string）：要选择的元素的说明
  ref （string）：页面快照中的精确目标元素引用
  values （array）：要选择的下拉选项值
• • **browser_choose_file：选择文件
• • 参数：
  paths （array）：要上传的文件的绝对路径。可以是单个文件或多个文件。
• • **browser_press_key：按键盘上的某个键
• • 参数：
  key （string）：要按下的键的名称或字符，例如 ArrowLeft 或
• • **browser_snapshot：捕获当前页面的辅助功能快照（比屏幕截图更好）
• • 参数： 无
• • **browser_save_as_pdf：将页面另存为 PDF
• • 参数： 无
• • browser_take_screenshot**：捕获页面的屏幕截图
  -参数： 无
• •browser_wait：等待指定时间
• • 参数：
  time （number）：等待时间（最长 10 秒）
• •browser_close：关闭页面
• • 参数： 无

视觉模式

对于基于屏幕截图的视觉交互，请使用以下命令启用它：

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

Vision 模式提供依赖于从屏幕截图中获取的坐标的 MCP 工具。典型的工作流程包括：

1. 1. 使用 browser_screenshot 捕获当前视图。
2. 2. 代理 （可能需要可视化处理功能） 分析屏幕截图以识别目标位置 （X、Y 坐标） 。
3. 3. 代理使用确定的坐标调用 browser_click 或 browser_type 等交互工具。

Vision Mode 提供了一套用于基于屏幕截图的视觉交互的工具。以下是所有可用的工具：

• • **browser_navigate：导航到 URL
  -参数：
  url （string）：要导航到的 URL
• • **browser_go_back：返回上一页
• • 参数： 无
• • **browser_go_forward：前进到下一页
  -参数： 无
• •browser_screenshot：捕获页面的屏幕截图
• • 参数： 无
• •browser_move_mouse：将鼠标移动到指定坐标
• • 参数：
• • x (number): X 坐标
• • y (number): Y 坐标
• •browser_click：点击元素
• • 参数：
• • x (number): X 坐标
• • y (number): Y 坐标
• •browser_drag：拖放元素
• • 参数：
• • startX （number）：起始 X 坐标
• • startY （number）：起始 Y 坐标
• • endX （number）：结束 X 坐标
• • endY （number）：结束 Y 坐标
• • browser_type**：输入文本（可选提交）
• • 参数：
• • x (number): X 坐标
• • y (number): Y 坐标
• • text (string): 要输入的文本
• • submit (boolean): 是否提交输入文本（之后按 Enter）
• • **browser_press_key：按键盘上的某个键
• • 参数：
• • key （string）：要按下的键的名称或字符，例如 ArrowLeft 或
• •browser_choose_file：选择文件
• • 参数：
• • paths （array）：要上传的文件的绝对路径。可以是单个文件或多个文件。
• • **browser_save_as_pdf：将页面另存为 PDF
• • 参数： 无
• •browser_wait：等待指定时间
• • 参数：
• • time （number）：等待时间（最长 10 秒）
• •browser_close：关闭页面
• • 参数： 无

自定义设置

除了配置文件和通过 IDE 自动启动之外，Playwright MCP 还可以直接集成到您的 Node.js 应用程序中。这提供了对服务器设置和通信传输的更多控制。

import { createServer } from"@playwright/mcp";
// Import necessary transport classes, e.g., from '@playwright/mcp/lib/sseServerTransport';
// Or potentially implement your own transport mechanism.

asyncfunctionrunMyMCPServer() {  // Create the MCP server instance  const server = createServer({    // You can pass Playwright launch options here    launchOptions: {      headless: true,      // other Playwright options...    },    // You might specify other server options if available  });
// Example using SSE transport (requires appropriate setup like an HTTP server)  // This part is conceptual and depends on your specific server framework (e.g., Express, Node http)  /*  const http = require('http');  const { SSEServerTransport } = require('@playwright/mcp/lib/sseServerTransport'); // Adjust path as needed
const httpServer = http.createServer((req, res) => {    if (req.url === '/messages' && req.method === 'GET') {      res.writeHead(200, {        'Content-Type': 'text/event-stream',        'Cache-Control': 'no-cache',        'Connection': 'keep-alive',      });      const transport = newSSEServerTransport("/messages", res); // Pass the response object      server.connect(transport); // Connect the MCP server to this transport
  req.on('close', () => {
    // Handle client disconnect if necessary
    server.disconnect(transport);
  });
} else {
  res.writeHead(404);
  res.end();
}

  });
  httpServer.listen(8931, () => {    console.log('MCP Server with SSE transport listening on port 8931');  });  */
// For simpler non-web transport, you might use other mechanisms  // server.connect(yourCustomTransport);
console.log("Playwright MCP server started programmatically.");
  // Keep the server running, handle connections, etc.  // Add cleanup logic for server shutdown.}

这种自定义方法允许精细控制、自定义传输层（超越默认机制或 SSE），并将 MCP 功能直接嵌入到更大的应用程序或代理框架中。

最佳实践

1. 1. 在大多数情况下，首选快照模式 – 更快、更可靠
2. 2. 仅在绝对需要视觉识别时使用视觉模式
3. 3. 清除敏感会话之间的用户配置文件
4. 4. 利用 Headless 模式实现自动化工作流程
5. 5. 结合 LLMs' 自然语言功能实现强大的自动化

结论

Microsoft Playwright MCP 为 AI 代理提供了一种强大而有效的方式LLMs来与 Web 交互。通过在默认快照模式下利用浏览器的辅助功能树，它提供了一种快速、可靠且文本友好的浏览器自动化方法，非常适合导航、数据提取和表单填写等常见任务。可选的视觉模式可作为需要与视觉元素进行基于坐标的交互的方案的后备方案。

Playwright MCP 通过 npx 进行简单安装，深度集成到 Cursor 等 Claude MCP 客户端中，以及灵活的配置选项（包括无头作和自定义传输），是一款多功能工具，可供开发人员构建下一代 Web 感知 AI 代理。通过了解其核心概念和可用工具，您可以有效地使您的应用程序和代理能够在广阔的 Internet 上导航和交互。