Playwright MCP 完整使用指南

Microsoft 官方出品的浏览器自动化 MCP Server，让 AI 助手能够控制浏览器进行网页操作。

简介

Playwright MCP 是微软基于 Playwright 开发的 Model Context Protocol 服务器，它允许 AI 代理通过结构化的方式与浏览器交互。

核心特点：

🎭 基于 Playwright 的强大浏览器自动化能力
📸 使用无障碍快照（Accessibility Snapshots）而非截图，更高效
🌐 支持 Chromium、Firefox、WebKit 三大浏览器引擎
🔒 内置安全机制，防止恶意操作
📱 支持移动端模拟

GitHub 地址： https://github.com/microsoft/playwright-mcp

前置要求

1. Node.js 环境

# 检查 Node.js 版本（需要 18+）
node --version

# 如果未安装，推荐使用 nvm 安装
nvm install 18
nvm use 18

2. npx 命令可用

# npx 随 npm 一起安装，检查是否可用
npx --version

安装方式

Playwright MCP 支持两种运行方式：

方式一：npx 直接运行（推荐）

无需安装，通过 npx 直接运行：

npx @playwright/mcp@latest

方式二：全局安装

npm install -g @playwright/mcp

# 运行
playwright-mcp

安装浏览器

首次运行时会自动下载浏览器，也可以手动安装：

npx playwright install chromium
# 或安装所有浏览器
npx playwright install

各 AI IDE 配置

Kiro

配置文件位置：

工作区级别：.kiro/settings/mcp.json
用户级别：~/.kiro/settings/mcp.json

配置内容：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "disabled": false,
      "autoApprove": [
        "browser_snapshot",
        "browser_navigate",
        "browser_click",
        "browser_type"
      ]
    }
  }
}

有头模式（可视化浏览器）：

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

Cursor

配置文件位置：

工作区级别：.cursor/mcp.json
用户级别：~/.cursor/mcp.json

配置内容：

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

Windows 系统特殊配置：

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

启用方式：

打开 Cursor 设置
搜索 "MCP"
确保 MCP 功能已启用
重启 Cursor

VS Code + Cline

配置文件位置： ~/.cline/mcp_settings.json 或通过 Cline 设置界面配置

配置内容：

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

通过 UI 配置：

打开 VS Code
点击 Cline 侧边栏图标
点击设置齿轮 → MCP Servers
添加新的 MCP Server
填入上述配置信息

VS Code + Continue

配置文件位置： ~/.continue/config.json

配置内容：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["@playwright/mcp@latest"]
        }
      }
    ]
  }
}

Windsurf

配置文件位置： ~/.windsurf/mcp.json

配置内容：

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

Claude Desktop

配置文件位置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

配置内容：

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

Windows 系统：

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

核心功能与工具

导航类

工具	说明
`browser_navigate`	导航到指定 URL
`browser_navigate_back`	返回上一页
`browser_navigate_forward`	前进到下一页

交互类

工具	说明
`browser_click`	点击页面元素
`browser_type`	在输入框中输入文本
`browser_hover`	鼠标悬停在元素上
`browser_drag`	拖拽元素
`browser_select_option`	选择下拉框选项
`browser_press_key`	按下键盘按键
`browser_file_upload`	上传文件

快照与截图

工具	说明
`browser_snapshot`	获取页面无障碍快照（推荐）
`browser_take_screenshot`	截取页面截图

标签页管理

工具	说明
`browser_tabs`	列出/创建/关闭/切换标签页
`browser_close`	关闭浏览器

其他

工具	说明
`browser_wait_for`	等待元素出现/消失
`browser_evaluate`	执行 JavaScript 代码
`browser_console_messages`	获取控制台消息
`browser_network_requests`	获取网络请求

使用示例

示例 1：打开网页并截图

请帮我打开 https://github.com 并截图

AI 会执行：

browser_navigate 导航到 GitHub
browser_take_screenshot 截取页面

示例 2：搜索并获取结果

请打开百度，搜索 "Playwright MCP"，然后告诉我搜索结果

AI 会执行：

browser_navigate 到百度
browser_snapshot 获取页面结构
browser_type 在搜索框输入关键词
browser_click 点击搜索按钮
browser_snapshot 获取搜索结果

示例 3：填写表单

请帮我打开登录页面，用户名填 test@example.com，密码填 123456

AI 会执行：

browser_navigate 到登录页
browser_snapshot 分析表单结构
browser_type 填写用户名
browser_type 填写密码

示例 4：测试网页功能

请测试我的网站 http://localhost:3000 的注册流程是否正常

AI 会自动：

打开网站
找到注册入口
填写注册表单
提交并验证结果

高级配置

完整配置选项

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless", "false",
        "--browser", "chromium",
        "--viewport-width", "1920",
        "--viewport-height", "1080"
      ],
      "env": {
        "PLAYWRIGHT_BROWSERS_PATH": "/path/to/browsers"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

常用参数说明

参数	说明	默认值
`--headless`	是否无头模式	`true`
`--browser`	浏览器类型	`chromium`
`--viewport-width`	视口宽度	`1280`
`--viewport-height`	视口高度	`720`
`--device`	模拟设备	-

模拟移动设备

{
  "args": [
    "@playwright/mcp@latest",
    "--device", "iPhone 14"
  ]
}

使用 Firefox

{
  "args": [
    "@playwright/mcp@latest",
    "--browser", "firefox"
  ]
}

使用 WebKit (Safari)

{
  "args": [
    "@playwright/mcp@latest",
    "--browser", "webkit"
  ]
}

常见问题

Q1: 提示浏览器未安装

解决方案：

npx playwright install chromium

或在配置中添加自动安装：

{
  "args": ["@playwright/mcp@latest", "--install-browser"]
}

Q2: Windows 下 npx 命令找不到

解决方案： 使用 cmd 包装

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

或使用完整路径：

{
  "command": "C:\\Program Files\\nodejs\\npx.cmd",
  "args": ["@playwright/mcp@latest"]
}

Q3: 连接超时

可能原因：

网络问题导致浏览器下载失败
防火墙阻止

解决方案：

手动安装浏览器：npx playwright install
检查防火墙设置
使用代理

Q4: 页面元素找不到

解决方案：

使用 browser_snapshot 获取最新页面结构
等待页面加载完成：browser_wait_for
检查元素是否在 iframe 中

Q5: 如何调试

启用有头模式查看操作：

{
  "args": ["@playwright/mcp@latest", "--headless", "false"]
}

查看控制台日志：

{
  "env": {
    "DEBUG": "pw:*"
  }
}

Q6: 如何处理登录状态

Playwright MCP 默认每次启动都是新的浏览器会话。如需保持登录状态：

使用 --user-data-dir 指定用户数据目录
或在每次会话中重新登录

安全注意事项

不要在生产环境使用 - Playwright MCP 主要用于开发和测试
注意敏感信息 - 避免让 AI 处理包含密码、密钥的页面
限制访问范围 - 可以通过配置限制可访问的域名
审查操作 - 在 Supervised 模式下审查 AI 的操作

更新日志

2024-12 - 初始版本

目录

简介

前置要求

1. Node.js 环境

2. npx 命令可用

安装方式

方式一：npx 直接运行（推荐）

方式二：全局安装

安装浏览器

各 AI IDE 配置

Kiro

Cursor

VS Code + Cline

VS Code + Continue

Windsurf

Claude Desktop

核心功能与工具

导航类

交互类

快照与截图

标签页管理

其他

使用示例

示例 1：打开网页并截图

示例 2：搜索并获取结果

示例 3：填写表单

示例 4：测试网页功能

高级配置

完整配置选项

常用参数说明

模拟移动设备

使用 Firefox

使用 WebKit (Safari)

常见问题

Q1: 提示浏览器未安装

Q2: Windows 下 npx 命令找不到

Q3: 连接超时

Q4: 页面元素找不到

Q5: 如何调试

Q6: 如何处理登录状态

安全注意事项

相关资源

更新日志

评论