Playwright MCP 实战示例

使用 Playwriter MCP 控制 Chrome 浏览器获取 X.com 书签的完整示例

项目简介

本项目展示了如何使用 Playwright MCP 来控制浏览器并自动化获取数据。Playwriter 是一个创新的 MCP 服务器，通过 Chrome 扩展的方式实现 AI 与浏览器的协作，相比传统方案具有更多优势。

核心功能

• ✅ 连接到现有 Chrome 浏览器（无需启动新实例）
• ✅ 自动获取 X.com (Twitter) 的书签内容
• ✅ 提取推文文本、作者、链接等信息
• ✅ 自动生成页面截图
• ✅ 完整的错误处理和用户提示

背景

本项目创建于探索浏览器自动化的过程中，通过实际案例展示了 Playwright MCP 的使用方法和最佳实践。

项目结构

playwriter-sample/
├── README.md                 # 项目说明文档
├── PLAYWRIGHT_SKILLS.md      # Playwright 使用完整指南
├── get-bookmarks.js          # 获取 X.com 书签的主脚本
├── package.json              # Node.js 项目配置
└── bookmarks-screenshot.png  # 截图输出（运行后生成）

技术栈

• Node.js - JavaScript 运行环境
• playwright-core - 浏览器自动化库
• playwriter - Playwright MCP 服务器
• Chrome Extension - Playwriter MCP 浏览器扩展

快速开始

前置要求

1. 安装 Chrome 扩展

   • 在 Chrome 网上应用店搜索 "Playwriter MCP"
   • 安装后固定到工具栏

2. 配置 Claude Code

   claude mcp add --transport stdio playwriter -- npx -y playwriter@latest

3. 验证安装

   claude mcp list

   应该看到 playwriter: npx -y playwriter@latest - ✓ Connected

安装依赖

npm install

使用步骤

1. 准备浏览器

   • 在 Chrome 中打开 https://x.com
   • 点击 Playwright 扩展图标，使其变绿（表示已连接）
   • 确保 X.com 处于登录状态

2. 运行脚本

   node get-bookmarks.js

3. 查看结果

   • 控制台会输出所有书签内容
   • 截图保存在 bookmarks-screenshot.png

示例输出

Connecting to browser via Playwriter relay server...
Current page: https://x.com/home
Navigating to bookmarks...
Waiting for bookmarks to load...

✅ Found 6 bookmarks:

--- Bookmark 1 ---
Author: Claude@claudeai·1月13日
Text: Introducing Cowork: Claude Code for the rest of the work.
Link: https://x.com/claudeai/status/2010805682434666759

...

📸 Screenshot saved to bookmarks-screenshot.png

核心代码说明

import { chromium } from 'playwright-core';
import { getCdpUrl } from 'playwriter';

// 连接到已运行的 Playwriter 服务器
const browser = await chromium.connectOverCDP(getCdpUrl());
const page = browser.contexts()[0].pages()[0];

// 导航到书签页面
await page.goto('https://x.com/i/bookmarks');

// 等待内容加载
await page.waitForTimeout(5000);

// 提取推文数据
const tweets = await page.evaluate(() => {
  const tweetElements = document.querySelectorAll('[data-testid="tweet"]');
  // ... 解析逻辑
});

await browser.close();

Playwright MCP 优势

特性	Playwriter	传统 Playwright	BrowserMCP
浏览器实例	使用现有浏览器	启动新实例	启动新实例
扩展支持	✅ 保留所有扩展	❌ 无扩展	❌ 无扩展
自动化检测	✅ 可绕过	❌ 总是被检测	❌ 总是被检测
资源占用	✅ 低	❌ 高	❌ 高
API 覆盖	✅ 完整 Playwright API	✅ 完整 Playwright API	❌ 有限工具集
工具数量	1 个 execute 工具	-	17+ 个工具

详细文档

查看 PLAYWRIGHT_SKILLS.md 获取完整的 Playwright 使用指南，包括：

• 安装配置详解
• 核心概念和架构
• 4 个实战案例
• 常用 API 参考
• 最佳实践
• 故障排除
• 进阶技巧

故障排除

无法连接到浏览器

# 检查 MCP 服务器状态
claude mcp list

# 确保 Chrome 扩展图标为绿色

端口被占用

# 查找占用端口的进程
lsof -i :19988

# 杀死进程
kill -9 <PID>

所有页面显示 about:blank

• 这是 Chrome 的已知 bug
• 需要完全重启 Chrome 浏览器（不只是扩展）

最佳实践

1. 等待策略 - 使用 waitForSelector 而非固定 waitForTimeout
2. 选择器稳定性 - 优先使用 data-testid 或语义化选择器
3. 错误处理 - 添加 try-catch 处理网络错误和超时
4. 调试技巧 - 使用截图和 slowMo 模式辅助调试

远程环境支持

支持在 Devcontainers/VM/SSH 环境中使用：

# 在宿主机（运行 Chrome）
npx playwriter serve --token <secret>

# 在容器/虚拟机（运行 Agent）
export PLAYWRITER_HOST="host.docker.internal"
export PLAYWRITER_TOKEN="<secret>"

扩展阅读

• Playwright 官方文档
• Playwright MCP GitHub
• MCP 规范

许可证

MIT License

作者

Created with Claude Code - 2025

---

最后更新：2025-01-14