playwright-mcp

通过 Playwright MCP 服务器实现浏览器自动化。浏览网站、单击元素、填写表单、提取数据、截取屏幕截图并执行完整的浏览器自动化工作流程。

# Playwright MCP Skill

Browser automation powered by Playwright MCP server. Control Chrome, Firefox, or WebKit programmatically.

## Installation

```bash
npm install -g @playwright/mcp
# Or
npx @playwright/mcp
```

Install browsers (first time):
```bash
npx playwright install chromium
```

## Quick Start

### Start MCP Server (STDIO mode)
```bash
npx @playwright/mcp
```

### Start with Options
```bash
# Headless mode
npx @playwright/mcp --headless

# Specific browser
npx @playwright/mcp --browser firefox

# With viewport
npx @playwright/mcp --viewport-size 1280x720

# Ignore HTTPS errors
npx @playwright/mcp --ignore-https-errors
```

## Common Use Cases

### 1. Navigate and Extract Data
```python
# MCP tools available:
# - browser_navigate: Open URL
# - browser_click: Click element
# - browser_type: Type text
# - browser_select_option: Select dropdown
# - browser_get_text: Extract text content
# - browser_evaluate: Run JavaScript
# - browser_snapshot: Get page structure
# - browser_close: Close browser
```

### 2. Form Interaction
```
1. browser_navigate to form URL
2. browser_type into input fields
3. browser_click to submit
4. browser_get_text to verify result
```

### 3. Data Extraction
```
1. browser_navigate to page
2. browser_evaluate to run extraction script
3. Parse returned JSON data
```

## MCP Tools Reference

| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to URL |
| `browser_click` | Click element by selector |
| `browser_type` | Type text into input |
| `browser_select_option` | Select dropdown option |
| `browser_get_text` | Get text content |
| `browser_evaluate` | Execute JavaScript |
| `browser_snapshot` | Get accessible page snapshot |
| `browser_close` | Close browser context |
| `browser_choose_file` | Upload file |
| `browser_press` | Press keyboard key |

## Configuration Options

```bash
# Security
--allowed-hosts example.com,api.example.com
--blocked-origins malicious.com
--ignore-https-errors

# Browser settings
--browser chromium|firefox|webkit
--headless
--viewport-size 1920x1080
--user-agent "Custom Agent"

# Timeouts
--timeout-action 10000      # Action timeout (ms)
--timeout-navigation 30000  # Navigation timeout (ms)

# Output
--output-dir ./playwright-output
--save-trace
--save-video 1280x720
```

## Examples

### Login to Website
```
browser_navigate: { url: "https://example.com/login" }
browser_type: { selector: "#username", text: "user" }
browser_type: { selector: "#password", text: "pass" }
browser_click: { selector: "#submit" }
browser_get_text: { selector: ".welcome-message" }
```

### Extract Table Data
```
browser_navigate: { url: "https://example.com/data" }
browser_evaluate: { 
  script: "() => { return Array.from(document.querySelectorAll('table tr')).map(r => r.textContent); }" 
}
```

### Screenshot
```
browser_navigate: { url: "https://example.com" }
browser_evaluate: { script: "() => { document.body.style.zoom = 1; return true; }" }
# Screenshot saved via --output-dir or returned in response
```

## Security Notes

- By default restricts file system access to workspace root
- Host validation prevents navigation to untrusted domains
- Sandboxing enabled by default (use `--no-sandbox` with caution)
- Service workers blocked by default

## Troubleshooting

```bash
# Update browsers
npx playwright install chromium

# Debug mode
npx @playwright/mcp --headless=false --output-mode=stdout

# Check installation
playwright-mcp --version
```

## Links

- [Playwright Docs](https://playwright.dev)
- [MCP Protocol](https://modelcontextprotocol.io)
- [NPM Package](https://www.npmjs.com/package/@playwright/mcp)

---

## 中文说明

# Playwright MCP 技能

由 Playwright MCP 服务器驱动的浏览器自动化。以编程方式控制 Chrome、Firefox 或 WebKit。

## 安装

```bash
npm install -g @playwright/mcp
# Or
npx @playwright/mcp
```

安装浏览器（首次）：
```bash
npx playwright install chromium
```

## 快速开始

### 启动 MCP 服务器（STDIO 模式）
```bash
npx @playwright/mcp
```

### 带选项启动
```bash
# Headless mode
npx @playwright/mcp --headless

# Specific browser
npx @playwright/mcp --browser firefox

# With viewport
npx @playwright/mcp --viewport-size 1280x720

# Ignore HTTPS errors
npx @playwright/mcp --ignore-https-errors
```

## 常见用例

### 1. 导航并提取数据
```python
# MCP tools available:
# - browser_navigate: Open URL
# - browser_click: Click element
# - browser_type: Type text
# - browser_select_option: Select dropdown
# - browser_get_text: Extract text content
# - browser_evaluate: Run JavaScript
# - browser_snapshot: Get page structure
# - browser_close: Close browser
```

### 2. 表单交互
```
1. browser_navigate to form URL
2. browser_type into input fields
3. browser_click to submit
4. browser_get_text to verify result
```

### 3. 数据提取
```
1. browser_navigate to page
2. browser_evaluate to run extraction script
3. Parse returned JSON data
```

## MCP 工具参考

| 工具 | 说明 |
|------|-------------|
| `browser_navigate` | 导航到 URL |
| `browser_click` | 通过选择器单击元素 |
| `browser_type` | 在输入框中键入文本 |
| `browser_select_option` | 选择下拉选项 |
| `browser_get_text` | 获取文本内容 |
| `browser_evaluate` | 执行 JavaScript |
| `browser_snapshot` | 获取可访问的页面快照 |
| `browser_close` | 关闭浏览器上下文 |
| `browser_choose_file` | 上传文件 |
| `browser_press` | 按下键盘按键 |

## 配置选项

```bash
# Security
--allowed-hosts example.com,api.example.com
--blocked-origins malicious.com
--ignore-https-errors

# Browser settings
--browser chromium|firefox|webkit
--headless
--viewport-size 1920x1080
--user-agent "Custom Agent"

# Timeouts
--timeout-action 10000      # Action timeout (ms)
--timeout-navigation 30000  # Navigation timeout (ms)

# Output
--output-dir ./playwright-output
--save-trace
--save-video 1280x720
```

## 示例

### 登录网站
```
browser_navigate: { url: "https://example.com/login" }
browser_type: { selector: "#username", text: "user" }
browser_type: { selector: "#password", text: "pass" }
browser_click: { selector: "#submit" }
browser_get_text: { selector: ".welcome-message" }
```

### 提取表格数据
```
browser_navigate: { url: "https://example.com/data" }
browser_evaluate: { 
  script: "() => { return Array.from(document.querySelectorAll('table tr')).map(r => r.textContent); }" 
}
```

### 截图
```
browser_navigate: { url: "https://example.com" }
browser_evaluate: { script: "() => { document.body.style.zoom = 1; return true; }" }
# Screenshot saved via --output-dir or returned in response
```

## 安全说明

- 默认将文件系统访问限制在工作区根目录
- 主机校验可防止导航到不受信任的域
- 默认启用沙箱（请谨慎使用 `--no-sandbox`）
- 默认阻止 Service Worker

## 故障排查

```bash
# Update browsers
npx playwright install chromium

# Debug mode
npx @playwright/mcp --headless=false --output-mode=stdout

# Check installation
playwright-mcp --version
```

## 链接

- [Playwright Docs](https://playwright.dev)
- [MCP Protocol](https://modelcontextprotocol.io)
- [NPM Package](https://www.npmjs.com/package/@playwright/mcp)