playwright-stealth

Playwright Stealth MCP Server

Playwright を使用したブラウザー自動化向けの Model Context Protocol（MCP）サーバーです。オプションのステルスモードを利用して、ボット対策を回避できます。

特長

• シンプルな API：多数の専用ツールではなく、Playwright API 全体を公開する単一の browser_execute ツール
• ステルスモード：playwright-extra と puppeteer-extra-plugin-stealth を使用した、オプションの検出対策
• 永続セッション：複数ステップの自動化に対応するため、ツール呼び出しの間もブラウザーセッションを維持
• スクリーンショットのサポート：視覚的な確認のため、ページのスクリーンショットをキャプチャ
• 動画録画：明示的な開始／停止操作で、ブラウザーの操作を WebM 動画として録画
• コード実行：page オブジェクトにアクセスして、任意の Playwright コードを実行
• すべての権限を付与：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 の操作（クリック、入力など）のデフォルトタイムアウト（ミリ秒）	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 は相互に排他的です。1 回の呼び出しで指定できるのは 1 つだけです。

戻り値：

• 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 に完全にアクセスできますが、セキュリティ上の影響があります。

• このサーバーは、信頼できる入力（例：制御された環境の LLM からの入力）に対してのみ使用してください
• コードは page オブジェクトにアクセスできる Node.js コンテキストで実行されます
• このサーバーを信頼できないユーザーやパブリックネットワークに公開しないでください

これは柔軟性を最大限に高めるための意図的な設計です。LLM が既存の 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 は実際の OS（例：「Linux x86_64」）を引き続き報告します。
• User-Agent とプラットフォームの不一致により、ボット検出が作動します。
• STEALTH_MASK_LINUX=false を設定すると、この偽装が無効になり、実際のプラットフォームが表示されます。
• これをカスタムの STEALTH_USER_AGENT と組み合わせると、一貫性のあるフィンガープリントを提示できます。

プロキシを使用する場面

次の場合は、プロキシ設定を構成してください。

• IP アドレスによるレート制限があるサイトをスクレイピングする場合
• 地域制限のあるコンテンツにアクセスする場合
• IP ベースのブロックや BAN を回避する場合
• 大規模なデータ収集のために 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 ツールを使用します。
• LLM のコンテキストウィンドウの使用量を削減します。
• LLM のトレーニングデータに含まれる既存の Playwright に関する知識を活用します。
• 人為的な制約なしに、API に完全にアクセスできます。

ライセンス

MIT