playwright-stealth

Playwright Stealth MCP 服务

一个用于浏览器自动化的 Model Context Protocol（MCP）服务，使用 Playwright，并可选启用隐身模式来绕过反机器人保护。

功能

• 简化的 API：提供单个 browser_execute 工具，开放完整的 Playwright API，而不是提供多个专用工具
• 隐身模式：可选使用 playwright-extra 和 puppeteer-extra-plugin-stealth 采取反检测措施
• 持久会话：浏览器会话在多次工具调用之间保持，以支持多步骤自动化
• 截图支持：捕获页面截图，用于视觉验证
• 视频录制：将浏览器交互录制为 WebM 视频，并通过明确的开始／停止控件进行控制
• 代码执行：运行任意 Playwright 代码，并访问 page 对象
• 完整权限：默认授予所有浏览器权限（通知、地理位置、摄像头等），以便测试 Web 应用

安装

npx playwright-stealth-mcp-server

或进行全局安装：

npm install -g playwright-stealth-mcp-server

配置

Claude Desktop 配置

添加到 Claude Desktop 配置文件中：

非隐身模式（标准 Playwright）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "playwright-stealth-mcp-server"],
      "env": {
        "STEALTH_MODE": "false"
      }
    }
  }
}

隐身模式（绕过反机器人保护）：

{
  "mcpServers": {
    "playwright-stealth": {
      "command": "npx",
      "args": ["-y", "playwright-stealth-mcp-server"],
      "env": {
        "STEALTH_MODE": "true"
      }
    }
  }
}

使用代理（例如，BrightData Residential Proxy）：

{
  "mcpServers": {
    "playwright-proxy": {
      "command": "npx",
      "args": ["-y", "playwright-stealth-mcp-server"],
      "env": {
        "STEALTH_MODE": "true",
        "PROXY_URL": "http://brd.superproxy.io:22225",
        "PROXY_USERNAME": "brd-customer-XXXXX-zone-residential",
        "PROXY_PASSWORD": "your-password"
      }
    }
  }
}

环境变量

变量	说明	默认值
STEALTH_MODE	启用隐身模式和反检测措施	false
STEALTH_USER_AGENT	自定义 User-Agent 字符串（仅限隐身模式）	浏览器默认值
STEALTH_MASK_LINUX	在 User-Agent 中将 Linux 伪装成 Windows；设为 false 可避免指纹不匹配	true
STEALTH_LOCALE	为 Accept-Language 标头设置自定义区域设置（仅限隐身模式）	en-US,en
HEADLESS	以无头模式运行浏览器	true
TIMEOUT	Playwright 操作（click、fill 等）的默认超时时间，单位为毫秒	30000
NAVIGATION_TIMEOUT	页面导航（goto、reload 等）的默认超时时间，单位为毫秒	60000
SCREENSHOT_STORAGE_PATH	截图存储目录	/tmp/playwright-screenshots
VIDEO_STORAGE_PATH	视频录制文件的存储目录	/tmp/playwright-videos
PROXY_URL	代理服务 URL（例如，http://proxy.example.com:8080）	-
PROXY_USERNAME	代理身份验证用户名	-
PROXY_PASSWORD	代理身份验证密码	-
PROXY_BYPASS	以逗号分隔的不使用代理的主机列表	-
BROWSER_PERMISSIONS	要授予的浏览器权限列表，以逗号分隔（见下文）	所有权限
IGNORE_HTTPS_ERRORS	忽略 HTTPS 证书错误（设为 false 可采用更严格的安全设置）	true

可用工具

browser_execute

执行可访问 page 对象的 Playwright 代码。

参数：

• code（必需）：要执行的 JavaScript 代码。page 对象在作用域内可用。
• timeout（可选）：执行超时时间，单位为毫秒。

示例：

await page.goto('https://example.com');
const title = await page.title();
return title;

browser_screenshot

截取当前页面、特定元素或页面区域的屏幕截图。截图会保存到文件系统存储中，之后可通过 MCP 资源访问。

参数：

• fullPage（可选）：截取可滚动页面的完整内容。默认值：false
• selector（可选）：要截取的特定元素的 CSS 选择器（例如 #main-content、.hero-banner、table.results）
• clip（可选）：要截取的页面区域，格式为 {x, y, width, height}，单位为像素
• resultHandling（可选）：结果处理方式：
  • saveAndReturn（默认）：保存到存储中，并以内联 base64 图像形式返回
  • saveOnly：保存到存储中，仅返回资源 URI（处理大型屏幕截图时更高效）

注意：fullPage、selector 和 clip 互斥。每次调用只能指定其中一个。

返回：

• 使用 saveAndReturn：内联 base64 PNG 图像，以及包含文件 URI 的 resource_link
• 使用 saveOnly：仅返回包含已保存屏幕截图 file:// URI 的 resource_link

browser_get_state

获取当前浏览器状态，包括 URL、标题和配置。

browser_close

关闭浏览器会话。下次调用 browser_execute 时会启动新的浏览器。

browser_start_recording

开始将浏览器会话录制为 WebM 视频。

此工具会回收浏览器上下文，并启用视频录制。会话状态（cookies、localStorage、sessionStorage）会在上下文回收过程中自动保留。

如果在录制过程中调用此工具，当前录制会自动停止并保存，然后开始新的录制。

browser_stop_recording

停止录制并保存视频。

返回包含已保存视频（WebM 格式）file:// URI 的 resource_link。会话状态会保留，浏览器会自动返回之前的 URL。

如果当前没有正在进行的录制，则返回错误。

MCP 资源

该服务将已保存的屏幕截图和视频录制内容作为 MCP 资源公开。客户端可以使用：

• resources/list：列出所有已保存屏幕截图和视频的 URI 及元数据
• resources/read：通过其 file:// URI 读取屏幕截图或视频

这样，客户端无需重新截图或录制，即可访问之前捕获的内容。

使用示例

导航并提取数据

// Navigate to a page
await page.goto('https://news.ycombinator.com');

// Extract headlines
const headlines = await page.$$eval('.titleline > a', (links) =>
  links.slice(0, 5).map((a) => a.textContent)
);

return headlines;

填写并提交表单

await page.goto('https://example.com/login');

// Fill credentials
await page.fill('input[name="email"]', '[email protected]');
await page.fill('input[name="password"]', 'password123');

// Submit form
await page.click('button[type="submit"]');

// Wait for navigation
await page.waitForNavigation();

return await page.title();

处理动态内容

await page.goto('https://spa-example.com');

// Wait for element to appear
await page.waitForSelector('.loaded-content');

// Click to load more
await page.click('.load-more-button');

// Wait for new content
await page.waitForSelector('.new-items');

const items = await page.$$eval('.item', (els) => els.map((el) => el.textContent));
return items;

安全注意事项

重要：browser_execute 工具会执行任意 JavaScript 代码。此设计提供完整的 Playwright API 访问权限，但也存在安全隐患：

• 仅在输入可信的情况下使用此服务（例如，在受控环境中接收来自大模型的输入）
• 代码会在可访问 page 对象的 Node.js 上下文中运行
• 请勿将此服务暴露给不可信用户或公共网络

此设计旨在提供最大的灵活性，让大模型能够利用已有的 Playwright 知识。用于生产环境时，请确保已设置适当的访问控制。

何时使用隐身模式

在以下情况下启用隐身模式（STEALTH_MODE=true）：

• 访问启用了 Cloudflare 防护的网站
• 访问会拦截自动化工具的网站
• 访问能够检测无头浏览器的页面
• 进行会触发 CAPTCHA 验证的 OAuth 流程

隐身模式包括：

• 屏蔽 WebDriver 属性
• 移除 Chrome 自动化标记
• 规范化 User-Agent
• 伪装插件和 MIME 类型
• 修补 Navigator 属性

指纹配置

在 Docker/Linux 环境中运行时，机器人检测系统可能会发现 User-Agent 标头与 navigator.platform 等其他浏览器信号之间的指纹不匹配。使用以下环境变量配置一致的指纹：

示例：macOS 指纹（适用于 Docker/Linux）

{
  "mcpServers": {
    "playwright-stealth": {
      "command": "npx",
      "args": ["-y", "playwright-stealth-mcp-server"],
      "env": {
        "STEALTH_MODE": "true",
        "STEALTH_USER_AGENT": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "STEALTH_MASK_LINUX": "false"
      }
    }
  }
}

为什么这很重要：

• 默认情况下，隐身模式仅在 User-Agent 标头中将 Linux 伪装成 Windows
• 但是，navigator.platform 仍会报告实际操作系统（例如，“Linux x86_64”）
• User-Agent 与平台之间的不匹配会触发机器人检测
• 设置 STEALTH_MASK_LINUX=false 会禁用此伪装，从而显示真实平台
• 配合自定义的 STEALTH_USER_AGENT，即可呈现一致的指纹

何时使用代理

在以下情况下配置代理设置：

• 抓取按 IP 地址进行速率限制的网站
• 访问受地理位置限制的内容
• 避免基于 IP 的屏蔽或封禁
• 为大规模数据采集轮换 IP

该服务支持带可选身份验证的 HTTP/HTTPS 代理，因此兼容：

• BrightData（住宅、数据中心、ISP 代理）
• Oxylabs、Smartproxy 和其他住宅代理提供商
• 自托管代理服务
• 企业 HTTP 代理

注意： 配置代理后，服务会在启动时执行健康检查，以验证代理连接是否正常。如果健康检查失败，服务将报错退出。

HTTPS 证书错误

默认情况下，服务会忽略 HTTPS 证书错误（IGNORE_HTTPS_ERRORS=true）。这对于常见的自动化场景很方便：

• Docker 环境，其中 SSL 证书可能与主机名不匹配
• 企业网络，其中的 MITM 代理会重新签署证书
• 开发或预发布环境中的自签名证书
• 会检查 HTTPS 流量的住宅代理

若要启用严格的证书验证，请设置 IGNORE_HTTPS_ERRORS=false：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "playwright-stealth-mcp-server"],
      "env": {
        "IGNORE_HTTPS_ERRORS": "false"
      }
    }
  }
}

安全提示： 对于证书验证至关重要的生产环境，请设置 IGNORE_HTTPS_ERRORS=false，以防范中间人攻击。

浏览器权限

默认情况下，服务会向浏览器上下文授予所有浏览器权限。这样便可以测试需要权限的功能，例如：

• Web 推送通知（notifications）
• 地理位置（geolocation）
• 摄像头/麦克风（camera、microphone）
• 剪贴板（clipboard-read、clipboard-write）
• MIDI 设备（midi、midi-sysex）
• 传感器（accelerometer、gyroscope、magnetometer、ambient-light-sensor）
• 其他（background-sync、local-fonts、payment-handler、storage-access）

限制权限

如果需要限制权限（例如，用于安全测试或模拟拒绝权限的用户），请使用 BROWSER_PERMISSIONS 环境变量：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "playwright-stealth-mcp-server"],
      "env": {
        "BROWSER_PERMISSIONS": "notifications,clipboard-read,clipboard-write"
      }
    }
  }
}

这将只授予指定的权限。所有其他权限请求都会被拒绝。

注意： 无效的权限名称会被静默忽略，并在服务日志中发出警告。如果无法识别某项权限，则会跳过该权限。

浏览器兼容性： 各浏览器对权限的支持有所不同。此服务默认使用 Chromium，支持所有列出的权限。如果使用 Firefox 或 WebKit，部分权限可能无法生效。

测试 Web 推送通知

使用默认配置（授予所有权限）时，可以测试 Web 推送通知：

// Check if notifications are supported and granted
const permission = await page.evaluate(() => Notification.permission);
console.log('Notification permission:', permission); // Should be "granted"

// Request notification permission (will auto-grant)
await page.evaluate(async () => {
  const result = await Notification.requestPermission();
  console.log('Permission result:', result);
});

// Create a test notification
await page.evaluate(() => {
  new Notification('Test Notification', {
    body: 'This is a test notification from Playwright',
  });
});

开发

# Install dependencies
npm run install-all

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run integration tests
npm run test:integration

# Run manual tests (requires Playwright browsers)
npm run test:manual:setup
npm run test:manual

架构

此 MCP 服务采用受 playwriter 启发的简化设计：

• 使用单个 browser_execute 工具，而非多个专用工具
• 减少大模型的上下文窗口占用
• 利用大模型训练数据中已有的 Playwright 知识
• 提供完整的 API 访问权限，不设人为限制

许可证

MIT