> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/microsoft/playwright-mcp) · [上游 README](https://github.com/microsoft/playwright-mcp/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
## Playwright MCP
一个基于 [Playwright](https://playwright.dev). 的 Model Context Protocol（MCP）服务器，提供浏览器自动化能力。该服务器使 LLM 能够通过结构化的可访问性快照与网页交互，无需截图或依赖视觉调优模型。
### Playwright MCP 与 Playwright CLI
本包为 Playwright 提供 MCP 接口。若你使用的是**编程代理（coding agent）**，使用 [CLI+SKILLS](https://github.com/microsoft/playwright-cli) 可能更合适。
- **CLI**：现代**编程代理**越来越倾向于将基于 CLI 的工作流以 SKILL 形式暴露，而不是 MCP，因为 CLI 调用更节省 token：它们避免将大型工具 schema 和冗长的可访问性树加载到模型上下文中，使代理能够通过简洁、专用的命令执行操作。这使得 CLI + SKILLs 更适合高吞吐的编程代理——这类代理必须在有限的上下文窗口内，在浏览器自动化与大型代码库、测试和推理之间取得平衡。
**了解更多：[Playwright CLI with SKILLS](https://github.com/microsoft/playwright-cli)**.**
- **MCP**：MCP 仍适用于受益于持久状态、丰富内省能力以及对页面结构进行迭代推理的专用智能体循环，例如探索性自动化、自愈测试，或长时间运行的自主工作流——在这些场景中，维持连续的浏览器上下文比 token 成本更重要。
### 主要特性
- **快速且轻量**。使用 Playwright 的可访问性树，而非基于像素的输入。
- **对 LLM 友好**。无需视觉模型，完全基于结构化数据运行。
- **确定性的工具调用**。避免基于截图方案常见的歧义。
### 要求
- Node.js 18 或更高版本
- VS Code、Cursor、Windsurf、Claude Desktop、Goose、Grok、Junie 或任何其他 MCP 客户端
### 快速开始
首先，在你的客户端中安装 Playwright MCP 服务器。
**标准配置**适用于大多数工具：
```js
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
```
[
](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [
](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
Amp
通过 Amp VS Code 扩展设置界面添加，或更新你的 settings.json 文件：
```json
"amp.mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
```
**Amp CLI 设置：**
通过下方 `amp mcp add` 命令添加
```bash
amp mcp add playwright -- npx @playwright/mcp@latest
```
Antigravity
通过 Antigravity 设置添加，或更新你的配置文件：
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
```
Claude Code
使用 Claude Code CLI 添加 Playwright MCP 服务器：
```bash
claude mcp add playwright npx @playwright/mcp@latest
```
Claude Desktop
按照 MCP 安装[指南](https://modelcontextprotocol.io/quickstart/user), 使用上方标准配置。
Cline
按照 [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers) 章节中的说明操作。
**示例：本地设置**
将以下内容添加到你的 [`cline_mcp_settings.json`](https://docs.cline.bot/mcp/configuring-mcp-servers#editing-mcp-settings-files) 文件中：
```json
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"timeout": 30,
"args": [
"-y",
"@playwright/mcp@latest"
],
"disabled": false
}
}
}
```
Codex
使用 Codex CLI 添加 Playwright MCP 服务器：
```bash
codex mcp add playwright npx "@playwright/mcp@latest"
```
或者，创建或编辑配置文件 `~/.codex/config.toml` 并添加：
```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
```
更多信息请参阅 [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).
Copilot
使用 Copilot CLI 以交互方式添加 Playwright MCP 服务器：
```bash
/mcp add
```
或者，创建或编辑配置文件 `~/.copilot/mcp-config.json` 并添加：
```json
{
"mcpServers": {
"playwright": {
"type": "local",
"command": "npx",
"tools": [
"*"
],
"args": [
"@playwright/mcp@latest"
]
}
}
}
```
更多信息请参阅 [Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).
Cursor
#### 点击按钮安装：
[
](https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
#### 或手动安装：
前往 `Cursor Settings` -> `MCP` -> `Add new MCP Server`。名称可自定，类型选择 `command`，命令为 `npx @playwright/mcp@latest`。也可通过点击 `Edit` 验证配置或添加命令参数。
Factory
使用 Factory CLI 添加 Playwright MCP 服务器：
```bash
droid mcp add playwright "npx @playwright/mcp@latest"
```
或者，在 Factory droid 中输入 `/mcp`，打开用于管理 MCP 服务器的交互式界面。
更多信息请参阅 [Factory MCP documentation](https://docs.factory.ai/cli/configuration/mcp).
Gemini CLI
按照 MCP 安装[指南](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), 使用上方标准配置。
Goose
#### 点击按钮安装：
[](https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright)
#### 或手动安装：
前往 `Advanced settings` -> `Extensions` -> `Add custom extension`。名称可自定，类型使用 `STDIO`，并将 `command` 设为 `npx @playwright/mcp`。点击 "Add Extension"。
Grok
使用 Grok CLI 添加 Playwright MCP 服务器：
```bash
grok mcp add playwright -- npx @playwright/mcp@latest
```
或者，创建或编辑配置文件 `~/.grok/config.toml` 并添加：
```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
```
更多信息请参阅 [Grok MCP documentation](https://docs.x.ai/build/features/mcp-servers).
Junie
在 Junie CLI 中添加 Playwright MCP 服务器：
1. 输入 `/mcp`
2. 按 `Ctrl+A` 添加新的 MCP 服务器
3. 从列表中选择 **Playwright**
或者，添加到 `.junie/mcp/mcp.json`：
```json
{
"mcpServers": {
"Playwright": {
"command": "npx",
"args": [
"-y",
"@playwright/mcp@latest"
]
}
}
}
```
更多信息请参阅 [Junie MCP 配置文档](https://junie.jetbrains.com/docs/junie-cli-mcp-configuration.html).
Kiro
[](https://kiro.dev/launch/mcp/add?name=playwright&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40playwright%2Fmcp%40latest%22%5D%7D)
请遵循 MCP Servers [文档](https://kiro.dev/docs/mcp/). 例如在 `.kiro/settings/mcp.json` 中：
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
```
LM Studio
#### 点击按钮安装：
[](https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)
#### 或手动安装：
在右侧边栏中转到 `Program` -> `Install` -> `Edit mcp.json`。使用上方的标准配置。
opencode
请遵循 MCP Servers [文档](https://opencode.ai/docs/mcp-servers/). 例如在 `~/.config/opencode/opencode.json` 中：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"playwright": {
"type": "local",
"command": [
"npx",
"@playwright/mcp@latest"
],
"enabled": true
}
}
}
```
Qodo Gen
在 VSCode 或 IntelliJ 中打开 [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) 聊天面板 → 连接更多工具 → + 添加新 MCP → 粘贴上方的标准配置。
点击 Save。
VS Code
#### 点击按钮安装：
[](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
#### 或手动安装：
请遵循 MCP 安装 [指南](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), 使用上方的标准配置。你也可以使用 VS Code CLI 安装 Playwright MCP 服务器：
```bash
# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
```
安装完成后，即可在 VS Code 中将 Playwright MCP 服务器用于你的 GitHub Copilot agent。
Warp
转到 `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` 以[添加 MCP 服务器](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). 使用上方的标准配置。
或者，在 Warp 提示符中使用斜杠命令 `/add-mcp`，并粘贴上方的标准配置：
```js
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
```
Windsurf
请遵循 Windsurf MCP [文档](https://docs.windsurf.com/windsurf/cascade/mcp). 使用上方的标准配置。
### 配置
Playwright MCP 服务器支持以下参数。你可以在上方 JSON 配置中提供它们，作为 `"args"` 列表的一部分：
| Option | Description |
|--------|-------------|
| --allowed-hosts | 逗号分隔的主机列表，指定此服务器允许提供服务的主机。默认为服务器绑定的主机。传入 '*' 可禁用主机检查。
*env* `PLAYWRIGHT_MCP_ALLOWED_HOSTS` |
| --allowed-origins | 分号分隔的受信任来源（TRUSTED origins）列表，允许浏览器发起请求。默认允许所有来源。重要：*不*构成安全边界，*不*影响重定向。
*env* `PLAYWRIGHT_MCP_ALLOWED_ORIGINS` |
| --allow-unrestricted-file-access | 允许访问工作区根目录之外的文件。同时允许无限制访问 file:// URL。默认情况下，文件系统访问仅限于工作区根目录（若未配置根目录则为 cwd），且禁止导航到 file:// URL。
*env* `PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS` |
| --blocked-origins | 分号分隔的来源列表，阻止浏览器发起请求。阻止列表在允许列表之前评估。若在未使用允许列表的情况下使用，不匹配阻止列表的请求仍会被允许。重要：*不*构成安全边界，*不*影响重定向。
*env* `PLAYWRIGHT_MCP_BLOCKED_ORIGINS` |
| --block-service-workers | 阻止 Service Worker
*env* `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS` |
| --browser | 要使用的浏览器或 Chrome 渠道，可选值：chrome、firefox、webkit、msedge。
*env* `PLAYWRIGHT_MCP_BROWSER` |
| --caps | 逗号分隔的额外功能列表，可选值：vision、pdf、devtools。
*env* `PLAYWRIGHT_MCP_CAPS` |
| --cdp-endpoint | 要连接的 CDP 端点。
*env* `PLAYWRIGHT_MCP_CDP_ENDPOINT` |
| --cdp-header | 随连接请求发送的 CDP 请求头，可指定多个。
*env* `PLAYWRIGHT_MCP_CDP_HEADERS` |
| --cdp-timeout | 连接 CDP 端点的超时时间（毫秒），默认为 30000ms
*env* `PLAYWRIGHT_MCP_CDP_TIMEOUT` |
| --codegen | 指定代码生成使用的语言，可选值："typescript"、"none"。默认为 "typescript"。
*env* `PLAYWRIGHT_MCP_CODEGEN` |
| --config | 配置文件路径。
*env* `PLAYWRIGHT_MCP_CONFIG` |
| --console-level | 要返回的控制台消息级别："error"、"warning"、"info"、"debug"。每个级别都包含更严重级别的消息。
*env* `PLAYWRIGHT_MCP_CONSOLE_LEVEL` |
| --device | 要模拟的设备，例如："iPhone 15"
*env* `PLAYWRIGHT_MCP_DEVICE` |
| --mobile | 模拟通用移动设备（Chromium 为 Pixel 10，WebKit 为 iPhone 17）。移动页面通常更轻量，可节省 token。不能与 --device 组合使用。
*env* `PLAYWRIGHT_MCP_MOBILE` |
| --executable-path | 浏览器可执行文件路径。
*env* `PLAYWRIGHT_MCP_EXECUTABLE_PATH` |
| --extension | 连接到正在运行的浏览器实例（仅 Edge/Chrome）。需要安装 "Playwright Extension"。
*env* `PLAYWRIGHT_MCP_EXTENSION` |
| --endpoint | 要连接的绑定浏览器端点。
*env* `PLAYWRIGHT_MCP_ENDPOINT` |
| --grant-permissions | 授予浏览器上下文的权限列表，例如 "geolocation"、"clipboard-read"、"clipboard-write"。
*env* `PLAYWRIGHT_MCP_GRANT_PERMISSIONS` |
| --headless | 以无头模式运行浏览器，默认为有界面模式
*env* `PLAYWRIGHT_MCP_HEADLESS` |
| --host | 服务器绑定的主机。默认为 localhost。使用 0.0.0.0 可绑定到所有网络接口。
*env* `PLAYWRIGHT_MCP_HOST` |
| --ignore-https-errors | 忽略 HTTPS 错误
*env* `PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS` |
| --init-page | 在 Playwright page 对象上求值的 TypeScript 文件路径
*env* `PLAYWRIGHT_MCP_INIT_PAGE` |
| --init-script | 作为初始化脚本添加的 JavaScript 文件路径。该脚本会在页面任何脚本之前在每个页面上求值。可多次指定。
*env* `PLAYWRIGHT_MCP_INIT_SCRIPT` |
| --isolated | 将浏览器配置文件保存在内存中，不写入磁盘。
*env* `PLAYWRIGHT_MCP_ISOLATED` |
| --image-responses | 是否向客户端发送图像响应。可为 "allow" 或 "omit"，默认为 "allow"。
*env* `PLAYWRIGHT_MCP_IMAGE_RESPONSES` |
| --no-sandbox | 为所有通常启用沙箱的进程类型禁用沙箱。
*env* `PLAYWRIGHT_MCP_NO_SANDBOX` |
| --output-dir | 输出文件目录路径。
*env* `PLAYWRIGHT_MCP_OUTPUT_DIR` |
| --output-max-size | 驱逐旧输出文件的阈值（字节）。
*env* `PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE` |
| --output-mode | 是否将快照、控制台消息、网络日志保存到文件或标准输出。可为 "file" 或 "stdout"。默认为 "stdout"。
*env* `PLAYWRIGHT_MCP_OUTPUT_MODE` |
| --port | SSE 传输监听的端口。
*env* `PLAYWRIGHT_MCP_PORT` |
| --proxy-bypass | 绕过代理的域名列表（逗号分隔），例如 ".com,chromium.org,.domain.com"
*env* `PLAYWRIGHT_MCP_PROXY_BYPASS` |
| --proxy-server | 指定代理服务器，例如 "http://myproxy:3128" 或 "socks5://myproxy:8080"
*env* `PLAYWRIGHT_MCP_PROXY_SERVER` |
| --sandbox | 为所有通常未启用沙箱的进程类型启用沙箱。
*env* `PLAYWRIGHT_MCP_SANDBOX` |
| --save-session | 是否将 Playwright MCP 会话保存到输出目录。
*env* `PLAYWRIGHT_MCP_SAVE_SESSION` |
| --secrets | 包含 dotenv 格式密钥的文件路径
*env* `PLAYWRIGHT_MCP_SECRETS_FILE` |
| --shared-browser-context | 在所有已连接的 HTTP 客户端之间复用同一浏览器上下文。
*env* `PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT` |
| --snapshot-mode | 为响应拍摄快照时指定使用的模式。可为 "full" 或 "none"。默认为 "full"。
*env* `PLAYWRIGHT_MCP_SNAPSHOT_MODE` |
| --storage-state | 隔离会话的 storage state 文件路径
*env* `PLAYWRIGHT_MCP_STORAGE_STATE` |
| --test-id-attribute | 指定用于测试 ID 的属性，默认为 "data-testid"
*env* `PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE` |
| --timeout-action | 指定操作超时时间（毫秒），默认为 5000ms
*env* `PLAYWRIGHT_MCP_TIMEOUT_ACTION` |
| --timeout-navigation | 指定导航超时时间（毫秒），默认为 60000ms
*env* `PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION` |
| --user-agent | 指定 User-Agent 字符串
*env* `PLAYWRIGHT_MCP_USER_AGENT` |
| --user-data-dir | 用户数据目录路径。若未指定，将创建临时目录。
*env* `PLAYWRIGHT_MCP_USER_DATA_DIR` |
| --viewport-size | 指定浏览器视口大小（像素），例如 "1280x720"
*env* `PLAYWRIGHT_MCP_VIEWPORT_SIZE` |
### 用户配置文件
你可以像在常规浏览器中一样，使用持久化配置文件（默认）运行 Playwright MCP，在隔离上下文中进行测试会话，或通过浏览器扩展连接到你现有的浏览器。
**持久化配置文件**
所有已登录信息都会保存在持久化配置文件中；如需清除离线状态，可以在会话之间删除它。
持久化配置文件位于以下位置，你可以使用 `--user-data-dir` 参数覆盖它。
```bash
# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}
# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}
# Linux
- ~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}
```
`{workspace-hash}` 派生自 MCP 客户端的工作区根目录，因此不同项目会自动获得独立的配置文件。
> [!IMPORTANT]
> 持久化配置文件同一时间只能被一个浏览器实例使用，因此共享同一工作区的并发 MCP 客户端会发生冲突。要并行运行多个客户端，请为每个额外客户端使用 `--isolated` 启动，或将其指向不同的 `--user-data-dir`。
**隔离模式**
在隔离模式下，每个会话都在隔离配置文件中启动。每当你要求 MCP 关闭浏览器时，
会话就会关闭，该会话的所有存储状态（storage state）也会丢失。你可以通过配置中的 `contextOptions` 或 `--storage-state` 参数向浏览器提供初始存储状态。了解更多关于存储状态的内容，请参见[此处](https://playwright.dev/docs/auth).
```js
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--isolated",
"--storage-state={path/to/storage.json}"
]
}
}
}
```
**浏览器扩展**
Playwright MCP Chrome 扩展允许你连接到现有的浏览器标签页，并利用你已登录的会话和浏览器状态。安装与设置说明请参见 [microsoft/playwright › packages/extension](https://github.com/microsoft/playwright/tree/main/packages/extension#readme)
### 初始状态
有多种方式可向浏览器上下文（browser context）或页面提供初始状态。
对于存储状态，你可以：
- 使用 `--user-data-dir` 参数，从用户数据目录（user data directory）启动。这会在会话之间持久保存所有浏览器数据。
- 使用 `--storage-state` 参数，从存储状态文件启动。这会将文件中的 cookies 和 local storage 加载到隔离的浏览器上下文中。
对于页面状态，你可以使用：
- `--init-page` 可指向一个 TypeScript 文件，该文件会在 Playwright 页面对象上执行。这允许你运行任意代码来设置页面。
```ts
// init-page.ts
export default async ({ page }) => {
await page.context().grantPermissions(['geolocation']);
await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
await page.setViewportSize({ width: 1280, height: 720 });
};
```
- `--init-script` 可指向一个 JavaScript 文件，该文件会作为初始化脚本添加。此脚本会在页面任何脚本之前于每个页面上执行。
这适用于覆盖浏览器 API 或设置环境。
```js
// init-script.js
window.isPlaywrightMCP = true;
```
### 配置文件
Playwright MCP 服务器可使用 JSON 配置文件进行配置。你可以使用 `--config` 命令行选项指定配置文件：
```bash
npx @playwright/mcp@latest --config path/to/config.json
```
配置文件模式（schema）
```typescript
{
/**
* The browser to use.
*/
browser?: {
/**
* The type of browser to use.
*/
browserName?: 'chromium' | 'firefox' | 'webkit';
/**
* Keep the browser profile in memory, do not save it to disk.
*/
isolated?: boolean;
/**
* Path to a user data directory for browser profile persistence.
* Temporary directory is created by default.
*/
userDataDir?: string;
/**
* Launch options passed to
* @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
*
* This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
*/
launchOptions?: playwright.LaunchOptions;
/**
* Context options for the browser context.
*
* This is useful for settings options like `viewport`.
*/
contextOptions?: playwright.BrowserContextOptions;
/**
* Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
*/
cdpEndpoint?: string;
/**
* CDP headers to send with the connect request.
*/
cdpHeaders?: Record;
/**
* Timeout in milliseconds for connecting to CDP endpoint. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
*/
cdpTimeout?: number;
/**
* Remote endpoint to connect to an existing Playwright server. May be a
* WebSocket URL string, or a [ConnectOptions] object that mirrors the
* `connectOptions` shape used by the test runner. When passed as an object,
* `exposeNetwork`, `headers`, `slowMo`, and `timeout` are forwarded to the
* underlying connect call.
*/
remoteEndpoint?: string | playwright.ConnectOptions & { endpoint: string };
/**
* Paths to TypeScript files to add as initialization scripts for Playwright page.
*/
initPage?: string[];
/**
* Paths to JavaScript files to add as initialization scripts.
* The scripts will be evaluated in every page before any of the page's scripts.
*/
initScript?: string[];
},
/**
* Connect to a running browser instance (Edge/Chrome only). If specified, `browser`
* config is ignored.
* Requires the "Playwright Extension" to be installed.
*/
extension?: boolean;
server?: {
/**
* The port to listen on for SSE or MCP transport.
*/
port?: number;
/**
* The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
*/
host?: string;
/**
* The hosts this server is allowed to serve from. Defaults to the host server is bound to.
* This is not for CORS, but rather for the DNS rebinding protection.
*/
allowedHosts?: string[];
},
/**
* List of enabled tool capabilities. Possible values:
* - 'core': Core browser automation features.
* - 'pdf': PDF generation and manipulation.
* - 'vision': Coordinate-based interactions.
* - 'devtools': Developer tools features.
*/
capabilities?: ToolCapability[];
/**
* Whether to save the Playwright session into the output directory.
*/
saveSession?: boolean;
/**
* Reuse the same browser context between all connected HTTP clients.
*/
sharedBrowserContext?: boolean;
/**
* Secrets are used to replace matching plain text in the tool responses to prevent the LLM
* from accidentally getting sensitive data. It is a convenience and not a security feature,
* make sure to always examine information coming in and from the tool on the client.
*/
secrets?: Record;
/**
* The directory to save output files.
*/
outputDir?: string;
/**
* Threshold for evicting old output files, in bytes.
*/
outputMaxSize?: number;
console?: {
/**
* The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".
*/
level?: 'error' | 'warning' | 'info' | 'debug';
},
network?: {
/**
* List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
*
* Supported formats:
* - Full origin: `https://example.com:8080` - matches only that origin
* - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
*/
allowedOrigins?: string[];
/**
* List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
*
* Supported formats:
* - Full origin: `https://example.com:8080` - matches only that origin
* - Wildcard port: `http://localhost:*` - matches any port on localhost with http protocol
*/
blockedOrigins?: string[];
};
/**
* Specify the attribute to use for test ids, defaults to "data-testid".
*/
testIdAttribute?: string;
timeouts?: {
/*
* Configures default action timeout: https://playwright.dev/docs/api/class-page#page-set-default-timeout. Defaults to 5000ms.
*/
action?: number;
/*
* Configures default navigation timeout: https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout. Defaults to 60000ms.
*/
navigation?: number;
/**
* Configures default expect timeout: https://playwright.dev/docs/test-timeouts#expect-timeout. Defaults to 5000ms.
*/
expect?: number;
};
/**
* 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.
*/
imageResponses?: 'allow' | 'omit';
snapshot?: {
/**
* When taking snapshots for responses, specifies the mode to use.
*/
mode?: 'full' | 'none';
};
/**
* allowUnrestrictedFileAccess acts as a guardrail to prevent the LLM from accidentally
* wandering outside its intended workspace. It is a convenience defense to catch unintended
* file access, not a secure boundary; a deliberate attempt to reach other directories can be
* easily worked around, so always rely on client-level permissions for true security.
*/
allowUnrestrictedFileAccess?: boolean;
/**
* Specify the language to use for code generation.
*/
codegen?: 'typescript' | 'none';
}
```
### 独立 MCP 服务器
在无显示器的系统上运行有界面（headed）浏览器，或从 IDE 的工作进程运行时，
请在配置了 DISPLAY 的环境中运行 MCP 服务器，并传入 `--port` 标志以启用 HTTP 传输。
```bash
npx @playwright/mcp@latest --port 8931
```
然后在 MCP 客户端配置中，将 `url` 设置为 HTTP 端点：
```js
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
```
## 安全
Playwright MCP **并非**安全边界。请参阅 [MCP Security Best Practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices)) 了解如何保护你的部署。
Docker
**注意：** 目前的 Docker 实现仅支持 headless chromium。
```js
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
}
}
}
```
或者，如果你希望将容器作为长期运行的服务，而不是由 MCP 客户端启动，请使用：
```
docker run -d -i --rm --init --pull=always \
--entrypoint node \
--name playwright \
-p 8931:8931 \
mcr.microsoft.com/playwright/mcp \
/app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0
```
服务器将在主机端口 **8931** 上监听，任何 MCP 客户端均可访问。
你可以自行构建 Docker 镜像。
```
docker build -t mcr.microsoft.com/playwright/mcp .
```
编程式使用
```js
import http from 'http';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
http.createServer(async (req, res) => {
// ...
// Creates a headless Playwright MCP server with SSE transport
const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
const transport = new SSEServerTransport('/messages', res);
await connection.connect(transport);
// ...
});
```
### 工具
核心自动化
- **browser_click**
- 标题：点击
- 描述：在网页上执行点击操作
- 参数：
- `element` (string, optional)：用于获取与元素交互权限的人类可读元素描述
- `target` (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
- `doubleClick` (boolean, optional)：是否执行双击而非单击
- `button` (string, optional)：要点击的按钮，默认为 left
- `modifiers` (array, optional)：要按下的修饰键
- 只读：**false**
- **browser_close**
- 标题：关闭浏览器
- 描述：关闭页面
- 参数：无
- 只读：**false**
- **browser_console_messages**
- 标题：获取控制台消息
- 描述：返回所有控制台消息
- 参数：
- `level` (string)：要返回的控制台消息级别。每个级别包含更严重级别的消息。默认为 "info"。
- `all` (boolean, optional)：返回自会话开始以来的所有控制台消息，而不仅仅是自上次导航以来的消息。默认为 false。
- `filename` (string, optional)：用于保存控制台消息的文件名。如未提供，则以文本形式返回消息。
- 只读：**true**
- **browser_drag**
- 标题：拖动鼠标
- 描述：在两个元素之间执行拖放操作
- 参数：
- `startElement` (string, optional)：用于获取与源元素交互权限的人类可读源元素描述
- `startTarget` (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
- `endElement` (string, optional)：用于获取与目标元素交互权限的人类可读目标元素描述
- `endTarget` (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
- 只读：**false**
- **browser_drop**
- 标题：将文件或数据拖放到元素上
- 描述：将文件或 MIME 类型的数据拖放到元素上，如同从页面外部拖入。必须至少提供 "paths" 或 "data" 之一。
- 参数：
- `element` (string, optional)：用于获取与元素交互权限的人类可读元素描述
- `target` (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
- `paths` (array, optional)：要拖放到元素上的文件的绝对路径。
- `data` (object, optional)：要拖放的数据，以 MIME 类型到字符串值的映射形式提供（例如 {"text/plain": "hello", "text/uri-list": "https://example.com"}）。
- 只读：**false**
- **browser_evaluate**
- 标题：执行 JavaScript
- 描述：在页面或元素上执行 JavaScript 表达式
- 参数：
- `element` (string, optional)：用于获取与元素交互权限的人类可读元素描述
- `target` (string, optional)：来自页面快照的精确目标元素引用，或唯一的元素选择器
- `function` (string)：() => { /* code */ } 或当提供 element 时为 (element) => { /* code */ }
- `filename` (string, optional)：用于保存结果的文件名。如未提供，则以文本形式返回结果。
- 只读：**false**
- **browser_file_upload**
- 标题：上传文件
- 描述：上传一个或多个文件
- 参数：
- `paths` (array, optional)：要上传文件的绝对路径。可以是单个文件或多个文件。如省略，则取消文件选择器。
- 只读：**false**
- **browser_fill_form**
- 标题：填写表单
- 描述：填写多个表单字段
- 参数：
- `fields` (array)：要填写的字段
- 只读：**false**
- **browser_find**
- 标题：在页面快照中查找
- 描述：在当前页面的无障碍（accessibility）快照中搜索文本或正则表达式。返回匹配的快照节点及少量周围上下文（类似搜索片段），每个节点均显示其在树中的路径；当你只需定位元素及其 ref 时，这比捕获整个快照更节省开销。
- 参数：
- `text` (string, optional)：要在页面快照中搜索的纯文本（不区分大小写的子串匹配）。请提供 text 或 regex 之一，不要同时提供。
- `regex` (string, optional)：要在页面快照中搜索的正则表达式。默认区分大小写；用斜杠包裹模式以添加标志，例如 "/error/i" 表示不区分大小写。请提供 text 或 regex 之一，不要同时提供。
- 只读：**true**
- **browser_handle_dialog**
- 标题：处理对话框
- 描述：处理对话框
- 参数：
- `accept` (boolean)：是否接受该对话框。
- `promptText` (string, optional)：在 prompt 对话框情况下，提示框的文本。
- 只读：**false**
- **browser_hover**
- 标题：悬停鼠标
- 描述：在页面元素上悬停
- 参数：
- `element` (string, optional)：用于获取与元素交互权限的人类可读元素描述
- `target` (string)：来自页面快照的精确目标元素引用，或唯一的元素选择器
- 只读：**false**
- **browser_navigate**
- Title: 导航到 URL
- Description: 导航到 URL
- Parameters:
- `url` (string): 要导航到的 URL
- Read-only: **false**
- **browser_navigate_back**
- Title: 后退
- Description: 返回历史记录中的上一页
- Parameters: None
- Read-only: **false**
- **browser_network_request**
- Title: 显示网络请求详情
- Description: 返回单个网络请求的完整详情（headers 和 body），若设置了 `part` 则仅返回其中一部分。请使用 browser_network_requests 输出的编号。
- Parameters:
- `index` (integer): 请求的 1-based 索引，与 browser_network_requests 输出的编号一致。
- `part` (string, optional): 仅返回请求的此部分。省略则返回完整详情。
- `filename` (string, optional): 将结果保存到的文件名。若未提供，则以文本形式返回输出。
- Read-only: **true**
- **browser_network_requests**
- Title: 列出网络请求
- Description: 返回自页面加载以来的网络请求编号列表。使用 browser_network_request 并传入编号可获取完整详情。
- Parameters:
- `static` (boolean): 是否包含成功的静态资源（如图片、字体、脚本等）。默认为 false。
- `filter` (string, optional): 仅返回 URL 匹配此正则表达式的请求（例如 "/api/.*user"）。
- `filename` (string, optional): 将网络请求保存到的文件名。若未提供，则以文本形式返回请求。
- Read-only: **true**
- **browser_press_key**
- Title: 按键
- Description: 在键盘上按下一个键
- Parameters:
- `key` (string): 要按下的键名或要生成的字符，例如 `ArrowLeft` 或 `a`
- Read-only: **false**
- **browser_resize**
- Title: 调整浏览器窗口大小
- Description: 调整浏览器窗口大小
- Parameters:
- `width` (number): 浏览器窗口宽度
- `height` (number): 浏览器窗口高度
- Read-only: **false**
- **browser_run_code_unsafe**
- Title: 运行 Playwright 代码（不安全）
- Description: 运行一段 Playwright 代码片段。不安全：在 Playwright 服务器进程中执行任意 JavaScript，等效于远程代码执行（RCE）。
- Parameters:
- `code` (string, optional): 包含待执行 Playwright 代码的 JavaScript 函数。将以单个参数 page 调用，可用于任意页面交互。例如：`async (page) => { await page.getByRole('button', { name: 'Submit' }).click(); return await page.title(); }`
- `filename` (string, optional): 从指定文件加载代码。若同时提供 code 和 filename，将忽略 code。
- Read-only: **false**
- **browser_select_option**
- Title: 选择选项
- Description: 在下拉框中选择选项
- Parameters:
- `element` (string, optional): 用于获取与元素交互权限的人类可读元素描述
- `target` (string): 来自页面快照的精确目标元素引用，或唯一元素选择器
- `values` (array): 要在下拉框中选择的值数组。可以是单个值或多个值。
- Read-only: **false**
- **browser_snapshot**
- Title: 页面快照
- Description: 捕获当前页面的无障碍（accessibility）快照，优于截图
- Parameters:
- `target` (string, optional): 来自页面快照的精确目标元素引用，或唯一元素选择器
- `filename` (string, optional): 将快照保存为 Markdown 文件，而非在响应中返回。
- `depth` (number, optional): 限制快照树的深度
- `boxes` (boolean, optional): 在快照中包含每个元素的边界框，格式为 [box=x,y,width,height]。坐标相对于视口，单位为 CSS 像素（Element.getBoundingClientRect）
- Read-only: **true**
- **browser_take_screenshot**
- Title: 截图
- Description: 对当前页面截图。无法基于截图执行操作，请使用 browser_snapshot 进行操作。
- Parameters:
- `element` (string, optional): 用于获取与元素交互权限的人类可读元素描述
- `target` (string, optional): 来自页面快照的精确目标元素引用，或唯一元素选择器
- `type` (string): 截图的图像格式。默认为 png。
- `filename` (string, optional): 保存截图的文件名。若未指定，默认为 `page-{timestamp}.{png|jpeg}`。建议使用相对文件名以保持在输出目录内。
- `fullPage` (boolean, optional): 为 true 时，截取完整可滚动页面的截图，而非当前可见视口。不能与元素截图同时使用。
- `scale` (string): 图像分辨率缩放。"css" 生成以 CSS 像素计尺寸的截图（较小，跨设备一致）。"device" 使用设备像素生成高分辨率截图（较大，考虑设备像素比）。默认为 css。
- Read-only: **true**
- **browser_type**
- Title: 输入文本
- Description: 在可编辑元素中输入文本
- Parameters:
- `element` (string, optional): 用于获取与元素交互权限的人类可读元素描述
- `target` (string): 来自页面快照的精确目标元素引用，或唯一元素选择器
- `text` (string): 要输入到元素中的文本
- `submit` (boolean, optional): 是否提交已输入的文本（之后按 Enter）
- `slowly` (boolean, optional): 是否逐字符输入。适用于触发页面中的按键处理程序。默认情况下会一次性填入全部文本。
- Read-only: **false**
- **browser_wait_for**
- Title: 等待
- Description: 等待文本出现或消失，或等待指定时间过去
- Parameters:
- `time` (number, optional): 等待时间（秒）
- `text` (string, optional): 要等待出现的文本
- `textGone` (string, optional): 要等待消失的文本
- Read-only: **false**
标签页管理
- **browser_tabs**
- Title: 管理标签页
- Description: 列出、创建、关闭或选择浏览器标签页。
- Parameters:
- `action` (string): 要执行的操作
- `index` (number, optional): 标签页索引，用于 close/select。close 时若省略，则关闭当前标签页。
- `url` (string, optional): 在新标签页中导航到的 URL，用于 new。
- Read-only: **false**
浏览器安装
配置（通过 --caps=config 可选启用）
- **browser_get_config**
- Title: 获取配置
- Description: 获取合并 CLI 选项、环境变量和配置文件后的最终解析配置。
- Parameters: None
- Read-only: **true**
网络（通过 --caps=network 可选启用）
- **browser_network_state_set**
- Title: 设置网络状态
- Description: 将浏览器网络状态设置为 online 或 offline。offline 时，所有网络请求都会失败。
- Parameters:
- `state` (string): 设为 "offline" 以模拟离线模式，设为 "online" 以恢复网络连接
- Read-only: **false**
- **browser_route**
- Title: 模拟网络请求
- Description: 设置路由以模拟匹配 URL 模式的网络请求
- Parameters:
- `pattern` (string): 要匹配的 URL 模式（例如 "**/api/users"、"**/*.{png,jpg}"）
- `status` (number, optional): 要返回的 HTTP 状态码（默认：200）
- `body` (string, optional): 响应体（文本或 JSON 字符串）
- `contentType` (string, optional): Content-Type 标头（例如 "application/json"、"text/html"）
- `headers` (array, optional): 以 "Name: Value" 格式添加的标头
- `removeHeaders` (string, optional): 要从请求中移除的标头名称列表，以逗号分隔
- Read-only: **false**
- **browser_route_list**
- Title: 列出网络路由
- Description: 列出所有活动的网络路由
- Parameters: None
- Read-only: **true**
- **browser_unroute**
- Title: 移除网络路由
- Description: 移除匹配指定模式的网络路由（若未指定模式则移除所有路由）
- Parameters:
- `pattern` (string, optional): 要取消路由的 URL 模式（省略则移除所有路由）
- Read-only: **false**
Storage（通过 --caps=storage 可选启用）
- **browser_cookie_clear**
- Title: 清除 Cookie
- Description: 清除所有 Cookie
- Parameters: None
- Read-only: **false**
- **browser_cookie_delete**
- Title: 删除 Cookie
- Description: 删除指定的 Cookie
- Parameters:
- `name` (string): 要删除的 Cookie 名称
- Read-only: **false**
- **browser_cookie_get**
- Title: 获取 Cookie
- Description: 按名称获取指定的 Cookie
- Parameters:
- `name` (string): 要获取的 Cookie 名称
- Read-only: **true**
- **browser_cookie_list**
- Title: 列出 Cookie
- Description: 列出所有 Cookie（可按域名/路径可选过滤）
- Parameters:
- `domain` (string, optional): 按域名过滤 Cookie
- `path` (string, optional): 按路径过滤 Cookie
- Read-only: **true**
- **browser_cookie_set**
- Title: 设置 Cookie
- Description: 设置 Cookie，并可选配置标志（domain、path、expires、httpOnly、secure、sameSite）
- Parameters:
- `name` (string): Cookie 名称
- `value` (string): Cookie 值
- `domain` (string, optional): Cookie 域名
- `path` (string, optional): Cookie 路径
- `expires` (number, optional): Cookie 过期时间（Unix 时间戳）
- `httpOnly` (boolean, optional): Cookie 是否为 HTTP only
- `secure` (boolean, optional): Cookie 是否为 secure
- `sameSite` (string, optional): Cookie SameSite 属性
- Read-only: **false**
- **browser_localstorage_clear**
- Title: 清除 localStorage
- Description: 清除所有 localStorage
- Parameters: None
- Read-only: **false**
- **browser_localstorage_delete**
- Title: 删除 localStorage 项
- Description: 删除 localStorage 项
- Parameters:
- `key` (string): 要删除的键
- Read-only: **false**
- **browser_localstorage_get**
- Title: 获取 localStorage 项
- Description: 按键获取 localStorage 项
- Parameters:
- `key` (string): 要获取的键
- Read-only: **true**
- **browser_localstorage_list**
- Title: 列出 localStorage
- Description: 列出所有 localStorage 键值对
- Parameters: None
- Read-only: **true**
- **browser_localstorage_set**
- Title: 设置 localStorage 项
- Description: 设置 localStorage 项
- Parameters:
- `key` (string): 要设置的键
- `value` (string): 要设置的值
- Read-only: **false**
- **browser_sessionstorage_clear**
- Title: 清除 sessionStorage
- Description: 清除所有 sessionStorage
- Parameters: None
- Read-only: **false**
- **browser_sessionstorage_delete**
- Title: 删除 sessionStorage 项
- Description: 删除 sessionStorage 项
- Parameters:
- `key` (string): 要删除的键
- Read-only: **false**
- **browser_sessionstorage_get**
- Title: 获取 sessionStorage 项
- Description: 按键获取 sessionStorage 项
- Parameters:
- `key` (string): 要获取的键
- Read-only: **true**
- **browser_sessionstorage_list**
- Title: 列出 sessionStorage
- Description: 列出所有 sessionStorage 键值对
- Parameters: None
- Read-only: **true**
- **browser_sessionstorage_set**
- Title: 设置 sessionStorage 项
- Description: 设置 sessionStorage 项
- Parameters:
- `key` (string): 要设置的键
- `value` (string): 要设置的值
- Read-only: **false**
- **browser_set_storage_state**
- Title: 恢复存储状态
- Description: 从文件恢复存储状态（Cookie、local storage）。恢复前会清除现有的 Cookie 和 local storage。
- Parameters:
- `filename` (string): 要从中恢复的存储状态文件路径
- Read-only: **false**
- **browser_storage_state**
- Title: 保存存储状态
- Description: 将存储状态（Cookie、local storage）保存到文件，供后续复用
- Parameters:
- `filename` (string, optional): 保存存储状态的文件名。若未指定，则默认为 `storage-state-{timestamp}.json`。
- Read-only: **true**
DevTools（通过 --caps=devtools 可选启用）
- **browser_annotate**
- Title: 标注当前页面
- Description: 以标注模式为当前页面打开 Playwright Dashboard，并等待用户绘制标注。返回带标注的截图、ARIA 快照以及标注列表。
- Parameters: None
- Read-only: **true**
- **browser_hide_highlight**
- Title: 隐藏元素高亮
- Description: 移除先前为该元素添加的高亮叠加层。
- Parameters:
- `element` (string, optional): 添加高亮时使用的人类可读元素描述；必须与传递给 browser_highlight 的值一致。
- `target` (string, optional): 页面快照中的精确目标元素引用，或唯一的元素选择器
- Read-only: **true**
- **browser_highlight**
- Title: 高亮元素
- Description: 在页面上显示围绕该元素的持久高亮叠加层。
- Parameters:
- `element` (string, optional): 用于获取与元素交互权限的人类可读元素描述
- `target` (string): 页面快照中的精确目标元素引用，或唯一的元素选择器
- `style` (string, optional): 应用于高亮叠加层的额外内联 CSS，例如 "outline: 2px dashed red"。
- Read-only: **true**
- **browser_resume**
- Title: 恢复已暂停的脚本执行
- Description: 在脚本暂停后恢复执行。当 step 设为 true 时，执行会在下一个操作前再次暂停。
- Parameters:
- `step` (boolean, optional): 为 true 时，执行会在下一个操作前再次暂停，以便逐步调试。
- `location` (string, optional): 在指定的 : 处暂停执行，例如 "example.spec.ts:42"。
- Read-only: **false**
- **browser_start_tracing**
- Title: 开始追踪
- Description: 开始记录追踪
- Parameters: 无
- Read-only: **true**
- **browser_start_video**
- Title: 开始录制视频
- Description: 开始录制视频
- Parameters:
- `filename` (string, optional): 用于保存视频的文件名。
- `size` (object, optional): 视频尺寸
- Read-only: **true**
- **browser_stop_tracing**
- Title: 停止追踪
- Description: 停止记录追踪
- Parameters: 无
- Read-only: **true**
- **browser_stop_video**
- Title: 停止录制视频
- Description: 停止录制视频
- Parameters: 无
- Read-only: **true**
- **browser_video_chapter**
- Title: 视频章节
- Description: 为视频录制添加章节标记。会显示带模糊背景的满屏章节卡片。
- Parameters:
- `title` (string): 章节标题
- `description` (string, optional): 章节描述
- `duration` (number, optional): 章节卡片显示时长（毫秒）
- Read-only: **true**
- **browser_video_hide_actions**
- Title: 隐藏操作叠加层
- Description: 停止标注页面上执行的操作。
- Parameters: 无
- Read-only: **true**
- **browser_video_show_actions**
- Title: 显示操作叠加层
- Description: 为页面上后续执行的操作添加标注：通过标注框显示操作名称并高亮目标元素。适用于视频录制或屏幕录制（screencasting）时。
- Parameters:
- `duration` (number, optional): 每个操作标注在屏幕上停留的时长（毫秒）。默认为 500。
- `position` (string, optional): 操作标题相对于页面的显示位置。默认为 top-right。
- `cursor` (string, optional): 指针操作的鼠标光标装饰。"pointer"（默认）会将鼠标指针从上一个操作点动画移动到下一个操作点；"none" 会禁用光标装饰。
- Read-only: **true**
基于坐标（通过 --caps=vision 可选启用）
- **browser_mouse_click_xy**
- Title: 点击
- Description: 在指定位置点击鼠标按钮
- Parameters:
- `x` (number): X 坐标
- `y` (number): Y 坐标
- `button` (string, optional): 要点击的按钮，默认为 left
- `clickCount` (number, optional): 点击次数，默认为 1
- `delay` (number, optional): 鼠标按下与松开之间的等待时间（毫秒），默认为 0
- Read-only: **false**
- **browser_mouse_down**
- Title: 按下鼠标
- Description: 按下鼠标
- Parameters:
- `button` (string, optional): 要按下的按钮，默认为 left
- Read-only: **false**
- **browser_mouse_drag_xy**
- Title: 拖动鼠标
- Description: 将鼠标左键拖动到指定位置
- Parameters:
- `startX` (number): 起始 X 坐标
- `startY` (number): 起始 Y 坐标
- `endX` (number): 结束 X 坐标
- `endY` (number): 结束 Y 坐标
- Read-only: **false**
- **browser_mouse_move_xy**
- Title: 移动鼠标
- Description: 将鼠标移动到指定位置
- Parameters:
- `x` (number): X 坐标
- `y` (number): Y 坐标
- Read-only: **false**
- **browser_mouse_up**
- Title: 松开鼠标
- Description: 松开鼠标
- Parameters:
- `button` (string, optional): 要松开的按钮，默认为 left
- Read-only: **false**
- **browser_mouse_wheel**
- Title: 滚动鼠标滚轮
- Description: 滚动鼠标滚轮
- Parameters:
- `deltaX` (number): X 增量
- `deltaY` (number): Y 增量
- Read-only: **false**
PDF 生成（通过 --caps=pdf 可选启用）
- **browser_pdf_save**
- Title: 另存为 PDF
- Description: 将页面另存为 PDF
- Parameters:
- `filename` (string, optional): 用于保存 PDF 的文件名。若未指定，则默认为 `page-{timestamp}.pdf`。建议使用相对文件名，以保留在输出目录内。
- Read-only: **true**
测试断言（通过 --caps=testing 可选启用）
- **browser_generate_locator**
- Title: 为元素创建定位器（locator）
- Description: 为给定元素生成定位器，供测试使用
- Parameters:
- `element` (string, optional): 用于获取与元素交互权限的人类可读元素描述
- `target` (string): 来自页面快照的精确目标元素引用，或唯一元素选择器
- Read-only: **true**
- **browser_verify_element_visible**
- Title: 验证元素可见
- Description: 验证元素在页面上可见
- Parameters:
- `role` (string): 元素的 ROLE。可在快照中这样找到：`- {ROLE} "Accessible Name":`
- `accessibleName` (string): 元素的 ACCESSIBLE_NAME。可在快照中这样找到：`- role "{ACCESSIBLE_NAME}"`
- Read-only: **false**
- **browser_verify_list_visible**
- Title: 验证列表可见
- Description: 验证列表在页面上可见
- Parameters:
- `element` (string): 人类可读的列表描述
- `target` (string): 指向该列表的精确目标元素引用
- `items` (array): 要验证的条目
- Read-only: **false**
- **browser_verify_text_visible**
- Title: 验证文本可见
- Description: 验证文本在页面上可见。如有可能，请优先使用 browser_verify_element_visible。
- Parameters:
- `text` (string): 要验证的 TEXT。可在快照中这样找到：`- role "Accessible Name": {TEXT}`，或这样：`- text: {TEXT}`
- Read-only: **false**
- **browser_verify_value**
- Title: 验证值
- Description: 验证元素值
- Parameters:
- `type` (string): 元素类型
- `element` (string): 人类可读的元素描述
- `target` (string): 来自页面快照的精确目标元素引用
- `value` (string): 要验证的值。对于复选框（checkbox），请使用 "true" 或 "false"。
- Read-only: **false**