如何在 Claude Code 中使用 Playwright MCP:浏览器自动化与代理设置

当网站更新布局或重命名 CSS 类时,常规的抓取脚本和 QA 脚本往往会立即失效。把 playwright-mcp 包连接到 Claude Code CLI,就能解决这个问题。通过 Model Context Protocol(MCP),浏览器会把页面的纯文本结构图直接发送给 AI 代理。你不必再手动查找 CSS 选择器,也不用向视觉模型发送体积庞大的截图。QA 工程师、爬虫开发者和分析师可以直接在终端中控制 Chromium、Firefox、WebKit 和 Microsoft Edge,同时让流量通过代理转发。

TL;DR:Claude Playwright MCP 工作流速览

• 工作原理:playwright-mcp 包向 Claude Code 发送轻量级的 playwright mcp 无障碍快照(browser_snapshot),而不是体积庞大的图像,最多可减少 80% 的 token 消耗。

• 一条命令完成配置:运行 claude mcp add playwright -- npx @playwright/mcp@latest,即可为单个文件夹、团队共享仓库或整台电脑全局注册官方 playwright mcp 服务器。

• 配置文件隔离:将 --isolated 参数与 --storage-state Cookie 文件(或单独的 --user-data-dir 文件夹)结合使用,可以并行运行多个浏览器窗口,而不会出现文件锁错误。

• 代理路由:在 .mcp.json 中传入 --proxy-server 和 HTTP_PROXY,即可让浏览器流量经由移动 LTE/5G 代理、静态住宅 ISP 代理或轮换住宅代理转发。

• 启动前检查 IP:在启动任务之前,请在 CyberYozh App 控制面板内置的 Fraud Score 检测工具中核查 IP 信誉。

👉 按国家和类型浏览 CyberYozh App 代理目录

Playwright MCP 在浏览器中做了什么

playwright mcp 与旧式浏览器工具有何不同?早期的视觉型 AI 代理会截取全屏图像,并按大致的 X、Y 像素坐标点击按钮。一旦弹出促销横幅或响应式布局发生变化,点击就会落空。

Microsoft 官方的 playwright mcp 服务器(@playwright/mcp)读取的是浏览器的无障碍树,而不是捕获像素。调用 browser_snapshot 会返回页面上所有交互元素的结构化文本图。每个按钮、链接或输入框都会获得精确的引用标签,例如 textbox "Search catalog" [ref=e5] 或 button "Apply filter" [ref=e12]。获取 playwright mcp 无障碍快照后,Claude Code 可以直接把 ref=e5 传给 browser_type 或 browser_click,无需猜测坐标。该服务器还能检查后台 API 流量(browser_network_requests)、读取控制台日志(browser_console_messages)、切换标签页,并导出 PDF 或截图(browser_pdf_save、browser_take_screenshot)。

这一工作流涵盖自动化数据采集的三个阶段。常规的网页抓取下载原始 HTML 代码,屏幕抓取读取 JavaScript 执行后浏览器中渲染出的可视数据,数据解析则将结构化字段提取为 CSV、Excel 或 JSON。借助 playwright-mcp,代理会在 JavaScript 渲染完成后读取实时 DOM 树,并立即提取结构化数据。

👉 了解 CyberYozh App 面向 AI 代理和浏览器自动化的代理基础设施

如何在终端中通过 Claude Code 使用 Playwright MCP

在真实网站上测试如何通过 Claude Code 使用 playwright mcp 之前,请先确认本机满足三项前提:Node.js 18 或更高版本(推荐 Node.js 20+ LTS)、已完成认证的 Claude Code CLI(@anthropic-ai/claude-code),以及可用的代理凭据,以避免触发频率限制。

如何将 Playwright MCP 添加到 Claude Code:三种配置模式

只需一条命令即可将 Playwright MCP 添加到 Claude Code,并通过 --scope 参数设置配置级别:local(当前文件夹)、project(团队共享仓库)或 user(全局配置)。本地文件夹的设置始终优先于项目设置和全局设置。

运行以下命令,检查已安装的版本、预先缓存 Chromium 二进制文件并注册服务器:

# 1. Check installed Node.js and Claude Code versions
node --version
claude --version

# 2. Pre-install the package and Chromium browser
npx @playwright/mcp@latest --version
npx playwright install chromium

# 3. Register the server (choose one of the three options)
# Option A: Only for the currently open folder
claude mcp add playwright -- npx @playwright/mcp@latest

# Option B: Globally for all your projects on this computer
claude mcp add playwright --scope user -- npx @playwright/mcp@latest

# Option C: Create a shared .mcp.json file in the project root for your team
claude mcp add playwright --scope project -- npx @playwright/mcp@latest

# 4. Verify the list of connected MCP servers
claude mcp list

运行 claude mcp add playwright 之后,你还可以安装社区版 ExecuteAutomation(@executeautomation/playwright-mcp-server),它提供覆盖 143 款智能手机和桌面设备型号的视口预设。如果你希望通过 Claude AI 抓取网站,又不想手动编辑配置文件,可以使用我们的开源项目 GitHub 上的 Yozh Scraper,它会自动让流量通过你的 CyberYozh App 代理转发。

👉 租用移动 LTE/5G 代理,每天 $1.70 起,流量不限

在 .mcp.json 中配置 Playwright MCP 代理

当 claude playwright mcp 会话用于检查本地化广告落地页、比较各地区价格或抓取商品目录时,来自同一个家庭或办公室 IP 的高频请求会触发验证码。在 .mcp.json(或 ~/.claude.json)中添加 playwright mcp 代理配置,即可让浏览器流量经由目标地区转发:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest",
        "--browser",
        "chromium",
        "--isolated",
        "--proxy-server=http://proxy.cyberyozh.com:8080"
      ],
      "env": {
        "HTTP_PROXY": "http://username:password@proxy.cyberyozh.com:8080",
        "HTTPS_PROXY": "http://username:password@proxy.cyberyozh.com:8080",
        "PLAYWRIGHT_MCP_PING_TIMEOUT_MS": "15000"
      }
    }
  }
}

注意:上面的服务器地址(proxy.cyberyozh.com)、端口(8080)、用户名和密码均为占位符。请替换为 CyberYozh App 控制面板中代理卡片上的主机、端口和登录凭据。

如何管理浏览器配置文件、Cookie 和代理 IP 的持续性

为避免并行运行时配置文件锁定导致崩溃,并防止会话意外重置,请把两种机制分开处理:

1. 浏览器 Cookie 和会话的存放位置:默认情况下,playwright-mcp 将 Cookie 和网站数据保存在磁盘上的同一个共享文件夹中。针对同一文件夹再打开第二个 Claude Code 终端会引发锁定错误。若要并行运行多个浏览器,请使用 --isolated 参数启动 playwright mcp 隔离配置文件(在内存中创建干净的配置文件),并通过 --storage-state=./auth.json 注入已保存的登录 Cookie。如果需要永久保存在磁盘上的配置文件,而不是内存中的 playwright mcp 隔离配置文件,请使用 --user-data-dir 为每个项目分配专用文件夹。

2. 如何保持代理 IP 一致:Cookie 与代理 IP 彼此独立。静态 IP 不会续期已过期的 Cookie 令牌,而如果结账过程中外部 IP 发生变化,已保存的 Cookie 也无法阻止登出。另请注意 Chromium 的一项限制:--proxy-server 参数仅在 HTTP/HTTPS 下接受用户名和密码。Chromium 中直接的 SOCKS5 连接只能配合控制面板中免密码的 IP 白名单使用,而带密码的 SOCKS5 需要本地代理转发工具(proxifier)。

👉 选择轮换住宅代理,$4.00/GB 起,sticky 会话最长 24 小时

为 playwright-mcp 选择哪种 CyberYozh App 代理

合适的代理类型取决于目标网站和会话时长。CyberYozh App 平台为浏览器自动化提供四种选择:

• 移动 LTE/4G/5G 代理(每天 $1.70 起,流量不限):运行在物理调制解调器和真实运营商 SIM 卡上。由于移动网络采用 CGNAT,数百名普通手机用户共用同一个运营商 IP。在多线程搜索抓取或广告检查期间,反欺诈过滤器和 Google 等搜索引擎限制该地址的可能性要小得多。私有套餐可通过控制面板链接或 REST API 更换 IP,共享套餐则按 5 分钟或 30 分钟的定时器轮换。支持 HTTP/HTTPS、SOCKS5、UDP、VPN/VLESS 配置,以及 TCP/IP 操作系统指纹切换。由于运营商基站会在其自身一侧定期刷新 IP 租约,建议先租用按天套餐,测试能否满足数小时运行所需的会话时长。

• 静态住宅 ISP 代理(每月 $5.29 起,流量不限):在整个租期内提供来自真实互联网服务提供商(ISP)的一个专属家庭 IP,正常运行时间 99.9%,支持 HTTP/HTTPS 和 SOCKS5。适用于客户和品牌项目、广告后台、管理面板和网店中持续数周乃至数月的会话。代理机构可以为每位客户把一个静态 ISP 代理绑定到专用的浏览器配置文件夹(--user-data-dir),使会话和 Cookie 永不混用。

• 轮换住宅代理(每 GB $4.00 起,最低 3 GB;购买 100 GB 时低至 $2.50/GB):可访问覆盖 195+ 个国家的 100M+ 住宅 IP。包含免费的国家、州/地区和城市定位、分配前的高级 IP 筛选、99.9% 的正常运行时间,以及最高 99.99% 的请求成功率。可按请求轮换以抓取商品目录,也可通过 sticky 会话将同一个 IP 保持最长 24 小时。未用完的流量会顺延到下一个计费月,批量凭据生成器(Mass Credentials Generator)和 REST API 则简化了批量配置。

• 数据中心(服务器)代理(每月 $1.77 起):提供专用和共享的 IPv4/IPv6 通道,专用套餐流量不限,正常运行时间 99.99%,适用于公开页面的高速抓取、可用性监控和 API 测试。

👉 选择适用于网页抓取和浏览器自动化的不限流量代理

通过 Fraud Score 检查 IP 信誉并排查常见错误

在将代理添加到 playwright-mcp 配置之前,请先在内置的 Fraud Score 风险检测工具中检查其 IP(每次 IP 检测 $0.15,或每月 $19.00 可进行 1,500 次 IP 检测、1,500 次手机号检测和 500 次银行卡检测,每月最多节省 $600)。该工具会查询 IPQualityScore (IPQS)、CyberSource、ThreatMetrix、Stripe Radar、PerimeterX 和 118 个 OSINT 黑名单,在你启动浏览器之前显示 ISP/ASN 标签、风险评分和 Abuse Velocity 状态。

要测试连接,请使用 MCP_TIMEOUT=10000 claude 启动客户端,让 npx 在首次运行时有足够的时间下载该包。在聊天中输入 /mcp,确认 playwright 显示绿色的 connected 状态。在第一条提示中请明确指明要使用的工具,这样 Claude 会打开浏览器,而不是编写脚本代码:

Use Playwright MCP: open https://app.cyberyozh.com/checkers/, read the page structure, and list the available checkers for verifying IP addresses, phone numbers, and cards.

如果你的自动化测试涉及短信注册表单或结账流程,可以在同一个 CyberYozh App 控制面板中租用用于接收短信的虚拟手机号,并开通虚拟卡。

👉 启动浏览器前先检查 IP 信誉和 Fraud Score

开始在 Claude Code 中使用浏览器自动化

将 playwright-mcp 与 Claude Code 结合,就能在终端里用纯文本命令控制真实浏览器:代理打开页面,通过无障碍树定位元素,并提取数据,无需依赖脆弱的选择器。再搭配 CyberYozh App 的移动 LTE/5G 代理、静态 ISP 代理或轮换住宅代理,无论在哪个地区,区域测试、店铺检查和商品目录抓取都能保持稳定。

👉 测试注册流程时,租用虚拟手机号接收短信验证码