playwright_mcp使用

如题，AI收集整理，作为了解

Playwright MCP 使用指南

概述

什么是 Playwright MCP

Playwright MCP（Model Context Protocol）是微软开源的一个基于模型上下文协议的服务器，它在大语言模型（LLM）和 Playwright 浏览器自动化框架之间架起了一座桥梁。

核心特性

✅ 轻量高效

• 基于 Playwright 的可访问性树（Accessibility Tree）

• 非像素级输入，性能更优

• 结构化数据交互，避免视觉依赖

✅ LLM 友好

• 纯结构化数据交互，无需视觉模型

• 降低集成复杂度

• 确定性操作，结果可预测

✅ 多模式支持

• 持久化配置文件：存储登录状态等数据

• 隔离模式：每次会话独立，关闭后状态清空

✅ 强大的自动化能力

• 支持 Chromium、Firefox、WebKit 三大浏览器引擎

• 自然语言驱动，无需编写复杂代码

• 智能元素定位，无需手动编写选择器

应用场景

场景	描述	效率提升
自动化测试	自然语言生成测试用例，自动执行	95%
数据抓取	智能网页数据提取，反爬规避	90%
办公自动化	表单填充、报告生成等重复任务	95%
AI 助手	让 AI 具备网页操作能力	80%

环境准备

系统要求

基础环境

• Node.js: v16+ 或 Python 3.8+

• 操作系统: Windows 10+, macOS 10.15+, Ubuntu 18.04+

• 内存: 建议 4GB 以上

• 磁盘空间: 至少 2GB（包含浏览器安装）

客户端支持

以下 AI 客户端支持 Playwright MCP：

• Cursor IDE: 推荐，原生支持 MCP 协议

• VS Code: 需要安装相关扩展

• Claude Desktop: 支持 MCP 功能

• 自定义 AI Agent: 通过 SDK 集成

网络要求

• 稳定的网络连接

• 部分场景可能需要代理（如访问海外网站）

安装配置

1. 安装 Playwright MCP 服务器

使用 npm 安装（推荐）

# 全局安装Playwright MCP
npm install -g @playwright/mcp@latest

# 验证安装
npx @playwright/mcp --version

使用 yarn 安装

# 使用yarn安装
yarn global add @playwright/mcp@latest

2. 安装浏览器驱动

# 安装Playwright所需的浏览器
npx playwright install

# 或者指定安装特定浏览器
npx playwright install chromium firefox webkit

3. 客户端配置

Cursor IDE 配置（推荐）

1. 打开 Cursor IDE

2. 进入设置（Settings）

3. 找到 MCP 配置（MCP Settings）

4. 添加以下配置：

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

VS Code 配置

1. 安装 Playwright 扩展

2. 创建.vscode/launch.json文件：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Playwright MCP",
      "program": "${workspaceFolder}/node_modules/@playwright/mcp/dist/cli.js",
      "args": ["--port", "8931"],
      "console": "integratedTerminal",
      "sourceMaps": true
    }
  ]
}

4. 启动服务器

基础启动

# 启动MCP服务器（默认配置）
npx @playwright/mcp

# 指定端口启动
npx @playwright/mcp --port 8931

# 启用SSE传输（推荐）
npx @playwright/mcp --port 8931 --sse

配置文件启动

创建mcp.config.json配置文件：

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "headless": true,
      "args": ["--no-sandbox"]
    }
  },
  "server": {
    "port": 8931,
    "host": "localhost"
  },
  "capabilities": ["core", "tabs", "pdf", "history"],
  "outputDir": "./output"
}

启动时指定配置文件：

npx @playwright/mcp --config mcp.config.json

5. 验证安装

启动成功后，您应该看到类似以下输出：

Playwright MCP Server v1.2.3
Listening on http://localhost:8931
Capabilities: core, tabs, pdf, history
Browser: chromium (headless)

基础使用

启动会话

通过命令行启动

# 启动交互式会话
npx @playwright/mcp --interactive

# 启动无头模式
npx @playwright/mcp --headless

通过客户端启动

在支持 MCP 的 AI 客户端中：

1. 确保 MCP 服务器已启动

2. 在客户端中启用 MCP 功能

3. 开始使用自然语言指令

基本操作示例

示例 1：简单网页导航

指令：

请访问百度首页，搜索"Playwright教程"，然后返回搜索结果的前5条标题

执行过程：

1. AI 调用browser_navigate导航到百度

2. 调用browser_type在搜索框输入关键词

3. 调用browser_click点击搜索按钮

4. 调用browser_snapshot获取页面快照

5. AI 解析快照，提取结果并整理

示例 2：数据提取

指令：

请访问GitHub Trending页面，获取今天最热门的5个Python项目的名称和星数

执行过程：

1. 导航到 GitHub Trending

2. 选择 Python 语言筛选

3. 提取项目信息

4. 格式化输出为表格

会话管理

持久化会话

# 启动持久化会话
npx @playwright/mcp --persist --user-data-dir ./session-data

# 恢复会话
npx @playwright/mcp --user-data-dir ./session-data

隔离会话

# 启动隔离会话（每次启动都是新的环境）
npx @playwright/mcp --isolated

核心工具详解

工具分类

Playwright MCP 提供了五大类工具，覆盖 Web 自动化全流程需求：

类别	工具数量	主要功能
基础操作	8 个	点击、输入、拖拽等基本交互
导航操作	3 个	页面跳转、前进后退
资源操作	4 个	截图、PDF、网络监控
实用工具	3 个	浏览器管理、窗口控制
标签页管理	4 个	多标签页操作

核心工具详细说明

1. 页面快照工具

browser_snapshot

功能：捕获当前页面的可访问性快照

参数：无

返回值：YAML 格式的可访问性树结构

使用示例：

{
  "name": "browser_snapshot",
  "parameters": {}
}

返回示例：

- Page URL: https://example.com
- Page Title: 示例页面
- Page Snapshot:
  - generic (active) (ref=e1): 页面内容区域
    - heading "登录表单" (ref=e2)
    - textbox "用户名" (ref=e3)
    - textbox "密码" (ref=e4)
    - button "登录" (ref=e5)

2. 导航工具

browser_navigate

功能：导航到指定 URL

参数：

• url: 目标 URL（必需）

使用示例：

{
  "name": "browser_navigate",
  "parameters": {
    "url": "https://www.baidu.com"
  }
}

browser_navigate_back

功能：返回上一页

参数：无

3. 元素交互工具

browser_click

功能：点击页面元素

参数：

• element: 元素描述（必需）

• ref: 元素引用 ID（必需，从快照获取）

• doubleClick: 是否双击（可选，默认 false）

使用示例：

{
  "name": "browser_click",
  "parameters": {
    "element": "搜索按钮",
    "ref": "e5",
    "doubleClick": false
  }
}

browser_type

功能：向可编辑元素输入文本

参数：

• element: 元素描述

• ref: 元素引用 ID

• text: 输入文本

browser_select_option

功能：选择下拉选项

参数：

• element: 下拉框描述

• ref: 下拉框引用 ID

• values: 要选择的值数组

4. 资源操作工具

browser_take_screenshot

功能：捕获页面截图

参数：

• raw: 是否返回无损 PNG（可选）

• filename: 保存文件名（可选）

• element: 元素描述（可选，局部截图）

browser_pdf_save

功能：将页面保存为 PDF

参数：

• filename: 保存文件名（可选）

5. 网络监控工具

browser_network_requests

功能：获取网络请求记录

参数：无

browser_console_messages

功能：获取控制台消息

参数：无

工具调用流程

一个完整的自动化流程通常包括：

1. 获取快照 → browser_snapshot

2. 分析页面 → AI 解析快照内容

3. 执行操作 → 调用相应的交互工具

4. 验证结果 → 获取新快照验证操作效果

实战案例

案例 1：自动化测试生成

需求

为一个电影搜索应用生成自动化测试用例

实施步骤

Step 1: 环境准备

# 创建测试项目
mkdir movie-test && cd movie-test
npm init -y
npm install @playwright/test

Step 2: 配置 Cursor MCP

在 Cursor 中配置 MCP 服务器，然后输入提示词：

你是一个Playwright测试生成器。
请访问 https://debs-obrien.github.io/playwright-movies-app
探索网站功能，然后生成完整的测试用例。
要求：
1. 使用基于角色的定位器
2. 包含适当的等待和断言
3. 覆盖主要功能点

Step 3: AI 探索与测试生成

AI 会自动：

• 访问网站

• 探索搜索功能、主题切换、分页等

• 发现潜在 bug（如搜索结果显示异常）

• 生成完整的测试代码

Step 4: 生成的测试代码

import { test, expect } from '@playwright/test';

test.describe('Movie Search Application', () => {
  test('Search for a movie by title', async ({ page }) => {
    // 访问应用
    await page.goto('https://debs-obrien.github.io/playwright-movies-app');
    
    // 验证首页加载
    await expect(page.getByRole('heading', { level: 1 })).toHaveText('Movie Search');
    
    // 点击搜索按钮
    await page.getByRole('search').click();
    
    // 输入搜索关键词
    const searchTerm = 'Star Wars';
    const searchInput = page.getByRole('textbox', { name: 'Search Input' });
    await searchInput.fill(searchTerm);
    await searchInput.press('Enter');
    
    // 验证搜索结果
    await expect(page).toHaveTitle(`${searchTerm} - Search Results`);
    await expect(page.getByRole('heading', { level: 1 })).toHaveText(searchTerm);
    await expect(page.getByRole('list', { name: 'movies' })).toBeVisible();
    
    // 点击第一个电影查看详情
    const firstMovie = page.getByRole('list', { name: 'movies' }).getByRole('link').first();
    const movieTitle = await firstMovie.getByRole('heading', { level: 2 }).textContent();
    await firstMovie.click();
    
    // 验证详情页
    await expect(page.getByRole('heading', { level: 1 })).toHaveText(movieTitle || '');
  });
});

案例 2：智能数据抓取

需求

从电商网站抓取商品信息并生成报告

实施步骤

Step 1: 编写抓取指令

请访问京东首页，搜索"笔记本电脑"，筛选价格在5000-8000元之间的产品，
获取前10个商品的名称、价格、评分和销量信息，
最后生成一个Markdown格式的产品对比表格。

Step 2: AI 执行抓取

AI 会：

• 导航到京东首页

• 在搜索框输入关键词

• 设置价格筛选条件

• 提取商品信息

• 处理分页和动态加载

• 格式化输出结果

Step 3: 生成的报告示例

排名	商品名称	价格	评分	销量
1	MacBook Air M2	¥7,999	4.9	10 万 +
2	ThinkPad X1 Carbon	¥7,499	4.8	5 万 +
3	Dell XPS 13	¥6,999	4.7	3 万 +

案例 3：办公自动化

需求

自动登录企业 OA 系统，填写日报表单

实施步骤

Step 1: 配置持久化会话

# 启动持久化会话
npx @playwright/mcp --persist --user-data-dir ./oa-session

Step 2: 编写自动化指令

请访问企业OA系统登录页面 https://oa.company.com/login
使用以下信息登录：
用户名：john.doe
密码：**********
登录后导航到日报填写页面，
填写今天的工作内容：
- 完成项目A的需求分析
- 参加团队周会
- 修复生产环境bug
提交表单后确认提交成功。

Step 3: 执行自动化

AI 会：

• 保存登录状态（后续无需重复登录）

• 自动填写表单

• 处理验证码（如需要人工协助）

• 提交并验证结果

最佳实践

1. 指令编写最佳实践

✅ 清晰明确的指令

不佳示例：

操作网站

优秀示例：

请在京东首页搜索框输入"智能手机"，点击搜索按钮，
然后获取前5个商品名称和价格，整理成表格。

✅ 提供必要的上下文

请访问GitHub Trending页面，选择"本月的"Python项目，
获取前3个项目的信息。注意：需要处理分页加载。

✅ 分步执行复杂任务

我们分两步执行：
1. 首先访问https://example.com/login登录系统
2. 登录成功后导航到/dashboard页面，获取今日数据

2. 元素定位策略

✅ 优先使用可访问性快照

{
  "name": "browser_snapshot",
  "parameters": {}
}

✅ 使用稳定的元素描述

• 优先使用角色定位：“登录按钮”、“搜索框”

• 避免使用位置描述：“页面底部的按钮”

✅ 处理动态内容

{
  "name": "browser_wait_for",
  "parameters": {
    "text": "加载完成",
    "time": 10
  }
}

3. 会话管理策略

持久化模式 vs 隔离模式

模式	适用场景	优点	缺点
持久化	需要保持登录状态的场景	无需重复登录	状态可能冲突
隔离模式	测试、数据抓取	环境干净	需要重复登录

会话管理代码示例

// 持久化会话配置
const persistConfig = {
  browser: {
    browserName: 'chromium',
    isolated: false,
    userDataDir: './persistent-session'
  }
};

// 隔离会话配置
const isolatedConfig = {
  browser: {
    browserName: 'chromium',
    isolated: true
  }
};

4. 错误处理最佳实践

✅ 重试机制

async function clickWithRetry(element, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      await element.click();
      return true;
    } catch (error) {
      if (i === retries - 1) throw error;
      await page.waitForTimeout(1000 * (i + 1));
    }
  }
}

✅ 超时设置

{
  "name": "browser_wait_for",
  "parameters": {
    "text": "提交成功",
    "time": 15
  }
}

5. 安全最佳实践

✅ 敏感信息处理

• 避免在指令中明文包含密码

• 使用环境变量存储敏感信息

• 及时清理会话数据

✅ 权限控制

{
  "network": {
    "allowedOrigins": ["https://trusted-domain.com"],
    "blockedOrigins": ["https://malicious-domain.com"]
  }
}

性能优化

1. 浏览器实例池化

实现原理

class BrowserPool {
  constructor(size = 3) {
    this.pool = [];
    this.size = size;
    this.init();
  }

  async init() {
    // 预热浏览器实例
    for (let i = 0; i < this.size; i++) {
      const browser = await playwright.chromium.launch();
      this.pool.push(browser);
    }
  }

  async acquire() {
    // 从池中获取实例
    if (this.pool.length === 0) {
      await this.waitForAvailable();
    }
    return this.pool.pop();
  }

  release(browser) {
    // 归还实例到池
    this.pool.push(browser);
  }
}

配置建议

• 池大小：3-5 个实例

• 定期重启：每 24 小时

• 内存监控：设置阈值自动重启

2. 并行执行优化

多会话并行

// 同时处理多个任务
const tasks = [
  { url: 'https://site1.com', action: 'extract' },
  { url: 'https://site2.com', action: 'screenshot' }
];

// 并行执行
const results = await Promise.all(
  tasks.map(task => processTask(task))
);

浏览器上下文隔离

// 为每个任务创建独立上下文
async function processTask(task) {
  const context = await browser.newContext();
  const page = await context.newPage();
  
  try {
    // 执行任务
    return await executeTask(page, task);
  } finally {
    // 清理资源
    await context.close();
  }
}

3. 网络优化

资源加载控制

{
  "browser": {
    "contextOptions": {
      "javaScriptEnabled": true,
      "images": false,  // 禁用图片加载
      "videos": false   // 禁用视频加载
    }
  }
}

缓存策略

// 启用HTTP缓存
const context = await browser.newContext({
  cache: {
    cacheStoragePath: './cache'
  }
});

4. 内存管理

启动参数优化

# 优化内存使用的启动参数
npx @playwright/mcp --browser-args="--disable-dev-shm-usage --single-process --disable-gpu"

资源清理

// 定期清理不活跃会话
setInterval(async () => {
  const inactiveSessions = getInactiveSessions();
  for (const session of inactiveSessions) {
    await session.cleanup();
  }
}, 3600000); // 每小时执行一次

5. 性能监控

关键指标监控

class PerformanceMonitor {
  constructor() {
    this.metrics = {
      responseTime: [],
      memoryUsage: [],
      successRate: []
    };
  }

  recordResponseTime(time) {
    this.metrics.responseTime.push(time);
  }

  recordMemoryUsage(usage) {
    this.metrics.memoryUsage.push(usage);
  }

  generateReport() {
    // 生成性能报告
    return {
      avgResponseTime: this.calculateAverage(this.metrics.responseTime),
      maxMemoryUsage: Math.max(...this.metrics.memoryUsage),
      successRate: this.calculateSuccessRate()
    };
  }
}

常见问题

1. 安装问题

Q: 安装时出现权限错误

问题：

Error: EACCES: permission denied, access '/usr/local/lib/node_modules'

解决方案：

# 方案1：使用sudo（不推荐）
sudo npm install -g @playwright/mcp

# 方案2：修复npm权限
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP /usr/local/lib/node_modules

# 方案3：使用nvm管理Node.js版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
nvm install 18
nvm use 18
npm install -g @playwright/mcp

Q: 浏览器安装失败

问题：

Failed to install browsers

解决方案：

# 手动安装浏览器
npx playwright install --force

# 设置代理（如果需要）
HTTPS_PROXY=http://proxy:port npx playwright install

2. 连接问题

Q: 客户端无法连接到 MCP 服务器

问题：

Connection refused: connect

解决方案：

# 1. 检查服务器是否正在运行
ps aux | grep playwright-mcp

# 2. 检查端口是否被占用
netstat -tlnp | grep 8931

# 3. 重启服务器
npx @playwright/mcp --port 8931

Q: 跨域访问被拒绝

问题：

CORS policy: No 'Access-Control-Allow-Origin' header

解决方案：

{
  "server": {
    "cors": {
      "allowedOrigins": ["*"]
    }
  }
}

3. 执行问题

Q: 元素定位失败

问题：

Element not found or not visible

解决方案：

[
  {
    "name": "browser_wait_for",
    "parameters": {
      "text": "登录",
      "time": 10
    }
  },
  {
    "name": "browser_snapshot",
    "parameters": {}
  },
  {
    "name": "browser_click",
    "parameters": {
      "element": "登录按钮",
      "ref": "e5"
    }
  }
]

Q: 页面加载超时

问题：

Timeout waiting for page to load

解决方案：

{
  "browser": {
    "contextOptions": {
      "navigationTimeout": 30000
    }
  }
}

4. 性能问题

Q: 内存使用过高

问题：

浏览器进程占用大量内存

解决方案：

# 1. 使用无头模式
npx @playwright/mcp --headless

# 2. 限制浏览器启动参数
npx @playwright/mcp --browser-args="--disable-dev-shm-usage --single-process"

# 3. 定期重启服务器

Q: 响应速度慢

问题：

AI 指令执行响应时间长

解决方案：

{
  "browser": {
    "contextOptions": {
      "images": false,
      "javaScriptEnabled": true
    }
  }
}

5. 安全问题

Q: 验证码处理

问题：

网站弹出验证码，AI 无法处理

解决方案：

1. 人工干预：暂停自动化，人工输入验证码

2. 第三方服务：集成验证码识别服务

3. 会话复用：使用已登录的浏览器会话

Q: 反爬虫检测

问题：

IP 被网站封禁

解决方案：

{
  "network": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "proxy": {
      "server": "http://proxy-server:port"
    }
  }
}

6. 兼容性问题

Q: 浏览器兼容性

问题：

某些功能在特定浏览器中不工作

解决方案：

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "channel": "chrome"
    }
  }
}

Q: 页面渲染问题

问题：

动态内容无法正确加载

解决方案：

{
  "name": "browser_wait_for",
  "parameters": {
    "text": "加载完成",
    "time": 15
  }
}

资源与参考

官方文档

Playwright MCP

• 官方文档

• GitHub 仓库

• API 参考

MCP 协议

• MCP 规范

• 协议文档

社区资源

学习资源

• Playwright 官方教程

• MCP 协议教程

• AI 自动化实践指南

示例项目

• Playwright MCP 示例

• AI 测试生成器

• 网页数据抓取工具

工具与扩展

开发工具

• Cursor IDE - 推荐的 MCP 客户端

• Playwright VS Code 扩展

• MCP 调试工具

第三方库

• @playwright/test - 测试框架

• @modelcontextprotocol/sdk - MCP SDK

• playwright-ai - AI 辅助工具

支持与反馈

获取帮助

• Playwright Slack 社区

• GitHub Issues

• Stack Overflow

报告问题

• Bug 报告

• 功能请求

• 性能问题

更新日志

最新版本

• v1.2.3 (2025-10-15)

• 新增 PDF 生成功能

• 优化内存使用

• 修复 Chrome 120 兼容性问题

版本计划

• v1.3.0 (预计 2025-11-30)

• 支持移动设备模拟

• 增强的网络监控

• 多语言支持