playwright-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

playwright-mcp

Purpose

用途

This skill provides a Playwright-based MCP server for browser automation, enabling programmatic control of web pages via the MCP protocol. It focuses on tasks like navigating sites, interacting with elements, and filling forms, integrated with OpenClaw for AI-driven workflows.

本Skill提供一个基于Playwright的MCP服务器，用于浏览器自动化，支持通过MCP协议以编程方式控制网页。它专注于网站导航、元素交互和表单填写等任务，并与OpenClaw集成以实现AI驱动的工作流。

When to Use

使用场景

Use this skill for automating browser interactions in scenarios like web scraping, UI testing, or dynamic form submissions. It's ideal when you need remote browser control, such as in CI/CD pipelines, data extraction from JavaScript-heavy sites, or simulating user actions across multiple pages.

当你需要在网页爬取、UI测试或动态表单提交等场景中自动化浏览器交互时，可以使用本Skill。它非常适合需要远程浏览器控制的场景，例如CI/CD流水线、从JavaScript密集型网站提取数据，或者跨多个页面模拟用户操作。

Key Capabilities

核心功能

Launch browsers (e.g., Chromium, Firefox) and manage sessions via MCP protocol.
Interact with page elements: select, click, or type using methods like
```
page.click('button')
```
.
Handle form filling and submissions: auto-populate fields and submit with
```
page.fill('input[name="username"]', 'user123')
```
.
Support for asynchronous operations: wait for elements with
```
page.waitForSelector('selector')
```
.
Error-resilient navigation: retry failed loads with built-in timeouts.
Configurable via JSON files, e.g., {"browser": "chromium", "headless": true}.

通过MCP协议启动浏览器（如Chromium、Firefox）并管理会话。
与页面元素交互：使用
```
page.click('button')
```
等方法选择、点击或输入内容。
处理表单填写与提交：自动填充字段并通过
```
page.fill('input[name="username"]', 'user123')
```
提交表单。
支持异步操作：使用
```
page.waitForSelector('selector')
```
等待元素加载。
具备错误恢复能力的导航：内置超时机制，可重试加载失败的页面。
可通过JSON文件配置，例如{"browser": "chromium", "headless": true}。

Usage Patterns

使用模式

To use this skill, start the MCP server and send commands from OpenClaw. Always initialize with authentication via

$PLAYWRIGHT_MCP_API_KEY

. Pattern 1: Launch a browser session and perform actions in sequence. Pattern 2: Use in loops for repetitive tasks, like form testing. For integration, wrap calls in try-catch blocks. Example pattern: Set up server with CLI, then use API endpoints to execute scripts.

要使用本Skill，需启动MCP服务器并从OpenClaw发送命令。初始化时必须通过

$PLAYWRIGHT_MCP_API_KEY

进行身份验证。模式1：启动浏览器会话并按顺序执行操作。模式2：在循环中用于重复任务，例如表单测试。集成时，将调用包裹在try-catch块中。示例模式：通过CLI设置服务器，然后使用API端点执行脚本。

Common Commands/API

常见命令/API

CLI: Run
```
playwright-mcp start --port 8080 --headless
```
to launch the server; add
```
--debug
```
for verbose logging.
API: POST to
```
/mcp/execute
```
with JSON payload, e.g., {"action": "navigate", "url": "https://example.com"}.

Code snippet for basic navigation:

const response = fetch('http://localhost:8080/mcp/execute', {
  method: 'POST',
  headers: {'Authorization': `Bearer ${process.env.PLAYWRIGHT_MCP_API_KEY}`},
  body: JSON.stringify({action: 'goto', url: 'https://example.com'})
});

For element interaction: Use
```
/mcp/interact
```
endpoint, e.g., POST with {"selector": '#id', "action": "click"}.
Config format: YAML or JSON, e.g., {"timeout": 30000, "retries": 3} in a file passed via
```
--config path/to/config.json
```
.
Authentication: Always include
```
$PLAYWRIGHT_MCP_API_KEY
```
in headers; check for 401 errors if missing.

CLI：运行
```
playwright-mcp start --port 8080 --headless
```
启动服务器；添加
```
--debug
```
以启用详细日志。
API：向
```
/mcp/execute
```
发送POST请求，携带JSON负载，例如{"action": "navigate", "url": "https://example.com"}。

基础导航代码片段：

const response = fetch('http://localhost:8080/mcp/execute', {
  method: 'POST',
  headers: {'Authorization': `Bearer ${process.env.PLAYWRIGHT_MCP_API_KEY}`},
  body: JSON.stringify({action: 'goto', url: 'https://example.com'})
});

元素交互：使用
```
/mcp/interact
```
端点，例如发送POST请求，携带{"selector": '#id', "action": "click"}。
配置格式：YAML或JSON，例如在通过
```
--config path/to/config.json
```
传入的文件中设置{"timeout": 30000, "retries": 3}。
身份验证：请求头中必须包含
```
$PLAYWRIGHT_MCP_API_KEY
```
；如果缺失，会返回401错误。

Integration Notes

集成说明

Integrate by running the server as a subprocess or via HTTP clients in OpenClaw. Set

$PLAYWRIGHT_MCP_API_KEY

as an environment variable for authentication. For example, in OpenClaw scripts, import as a module and call functions like

mcpClient.execute({action: 'fill', selector: 'input', value: 'data'}). Use WebSockets for real-time updates on

/mcp/ws

. Ensure compatibility with Node.js 14+; handle CORS by adding

--allow-origins *` to CLI. Test integrations with mock servers to simulate failures.

可通过在OpenClaw中将服务器作为子进程运行，或通过HTTP客户端进行集成。将

$PLAYWRIGHT_MCP_API_KEY

设置为环境变量以进行身份验证。例如，在OpenClaw脚本中，将其作为模块导入并调用

mcpClient.execute({action: 'fill', selector: 'input', value: 'data'})

等函数。使用WebSocket连接

/mcp/ws

以获取实时更新。确保与Node.js 14+兼容；通过在CLI中添加

--allow-origins *

解决CORS问题。使用模拟服务器测试集成以模拟故障场景。

Error Handling

错误处理

Common errors include timeout exceptions (e.g., network delays) or selector failures; use

page.waitForTimeout(5000)

before actions. For API errors, check response codes: 404 for invalid endpoints, 500 for server issues. Handle with try-catch in code, e.g.:

try {
  await page.click('nonexistent');
} catch (error) {
  console.error('Element not found:', error.message);
  // Retry or fallback
}

Prescribe logging all errors with

--debug

flag. For authentication failures, verify

$PLAYWRIGHT_MCP_API_KEY

and retry. Use exponential backoff for transient errors like 429 (rate limit).

常见错误包括超时异常（如网络延迟）或选择器定位失败；在执行操作前可使用

page.waitForTimeout(5000)

等待。对于API错误，检查响应代码：404表示端点无效，500表示服务器问题。在代码中使用try-catch块处理，例如：

try {
  await page.click('nonexistent');
} catch (error) {
  console.error('Element not found:', error.message);
  // 重试或执行回退逻辑
}

建议使用

--debug

标志记录所有错误。对于身份验证失败，验证

$PLAYWRIGHT_MCP_API_KEY

后重试。对于429（速率限制）等临时错误，使用指数退避策略。

Concrete Usage Examples

具体使用示例

Automate form filling: Start server with
```
playwright-mcp start --port 8080
```
, then send API call to fill and submit a login form: POST
```
/mcp/execute
```
with {"action": "fill", "selector": '#username', "value": "testuser", "then": "click('#submit')"}. This extracts data or verifies login success.
Web scraping task: Use in OpenClaw to navigate to a page and extract content: CLI command
```
playwright-mcp execute --url 'https://site.com' --script 'page.evaluate(() => document.querySelector("#data").textContent)'
```
, then process the output for analysis.

自动化表单填写：使用
```
playwright-mcp start --port 8080
```
启动服务器，然后发送API请求以填写并提交登录表单：向
```
/mcp/execute
```
发送POST请求，携带{"action": "fill", "selector": '#username', "value": "testuser", "then": "click('#submit')"}。此操作可用于提取数据或验证登录是否成功。
网页爬取任务：在OpenClaw中使用本Skill导航到页面并提取内容：执行CLI命令
```
playwright-mcp execute --url 'https://site.com' --script 'page.evaluate(() => document.querySelector("#data").textContent)'
```
，然后处理输出结果以进行分析。

Graph Relationships

关联关系

Related to: browser-automation (depends on for core functionality), web-scraping (extends for data extraction), mcp-protocol (implements as base).
Clusters: community (part of), automation-tools (links to for broader ecosystem).
Dependencies: playwright-core (requires for browser control), mcp-server (bases on for protocol handling).

相关技能：browser-automation（核心功能依赖）、web-scraping（扩展用于数据提取）、mcp-protocol（作为基础协议实现）。
所属集群：community（社区成员）、automation-tools（链接至更广泛的生态系统）。
依赖项：playwright-core（用于浏览器控制）、mcp-server（基于其处理协议）。