Puppeteer MCP — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

最小限のAPI — 7つのツールでブラウザ自動化ニーズの90%をカバー
Chromium専用 — インストールが速く、追加のブラウザバイナリ不要
CSSセレクターベース — DOMを知っていれば予測可能で学習コストなし
注意: リポジトリはアーカイブ済み。新規案件にはplaywright MCPを推奨

ライブデモ

実際の動作

puppeteer.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "puppeteer",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

{
  "context_servers": {
    "puppeteer": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-puppeteer"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： Puppeteer

URLリストのスクリーンショットを撮ってビジュアル監査を行う

👤 QA、デザイナー、コンテンツ管理者 ⏱ ~10 min beginner

使うタイミング： 変更後にページ一覧を目視確認したいとき。

フロー

ナビゲートしてキャプチャ

For each URL in [list], navigate, wait for load, take a full-page screenshot named <slug>.png.✓ コピーしました

→ N件のスクリーンショットが保存される
ベースラインとの差分比較（任意）

Compare each screenshot to the matching file in ./baseline/. Flag any that differ by more than 5% pixel diff.✓ コピーしました

→ 変更があったページのリスト
結果のまとめ

Write a 1-paragraph summary: how many pages, how many changed, which likely need review.✓ コピーしました

→ PRの説明にそのまま貼れる簡潔なステータス

結果： ビジュアルリグレッションパイプラインを構築せずに、ベースライン用のスクリーンショットセットと差分レポートが得られます。

注意点

動的コンテンツ（日付、A/Bバナー）が偽の差分を生む — スクリーンショット前にpuppeteer_evaluateでCSSを使ってそれらの要素を非表示にする

組み合わせ： filesystem

テストデータでフォームを繰り返し入力する

👤 QAエンジニア、入力フローをテストするバックエンド開発者 ⏱ ~15 min intermediate

使うタイミング： バリデーション検証のために20パターンの入力でフォームをテストしたいとき。

前提条件

テスト環境のURL — 本番環境では絶対に実行しないこと — ステージングインスタンスを立ち上げてください

フロー

フォームに移動

Open https://staging.app/signup. Take a screenshot to confirm.✓ コピーしました

→ ページが読み込まれ、フォームが表示される
テストケースを送信

For each test case [list: {email, password, expected_error}], fill the fields, click submit, and capture the error message element's text.✓ コピーしました

→ 各ケースの実際の結果と期待値の比較
不一致を報告

Summarize: which cases passed, which failed, what the gap was. Take a screenshot of each failure.✓ コピーしました

→ エビデンス付きのテストレポート

結果： Playwrightのスペックを書くほどでもないバリデーションカバレッジを10分で実現できます。

注意点

前回のフォーム状態が実行間で残る — ケース間でpuppeteer_navigateを呼んでURLを更新するか、セレクターベースのpuppeteer_fillに空文字を渡してフィールドを明示的にクリアする

ページ上のリンク切れ・表示されない画像を検出する

👤 コンテンツ/ドキュメント管理者 ⏱ ~10 min intermediate

使うタイミング： サイト移行やCMS変更後 — リンク切れ画像はよくある恥ずかしいミスです。

フロー

ページを読み込む

Open <URL>. Wait 2 seconds for lazy-loaded images.✓ コピーしました

→ ページが読み込まれた
evaluateでリンク切れ画像を検出

Run page.evaluate to return every <img> where naturalWidth === 0 — those failed to load. Include src and alt for each.✓ コピーしました

→ リンク切れ画像ソースのリスト
サイト全体で繰り返す

Repeat for these 20 URLs. Output a CSV of page, broken-img-src, alt-text.✓ コピーしました

→ 対応可能なCSV

結果： リンク切れ画像とそれが存在するページの具体的な修正リストが得られます。

注意点

遅延読み込み画像がまだトリガーされていない — evaluateでwindow.scrollTo(0, document.body.scrollHeight)を実行してページを先にスクロールし、待機してから確認する

組み合わせ： filesystem

組み合わせ

他のMCPと組み合わせて10倍の力を

puppeteer + filesystem

すべてのページのスクリーンショットを撮り、レビュー用に画像ファイルとして保存する

Open each URL in urls.txt, take a full-page screenshot, save to ./audit/<slug>.png.✓ コピーしました

puppeteer + sentry

Sentryで報告されたエラーをユーザーの操作パスを再現して再現する

Sentry issue WEB-3a91 has breadcrumbs showing the user clicked .checkout-btn then filled #card-number. Reproduce that in Puppeteer and capture the console.✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
puppeteer_navigate	url	URLを開くまたはリダイレクトする	free
puppeteer_screenshot	name, selector?, width?, height?	ページまたは特定の要素をキャプチャする	disk space
puppeteer_click	selector	CSSセレクターで要素をクリックする	free
puppeteer_fill	selector, value	入力フィールドにテキストを入力する	free
puppeteer_select	selector, value	`<select>`からオプションを選択する	free
puppeteer_hover	selector	ホバー専用のメニューやツールチップを表示する	free
puppeteer_evaluate	script	ページコンテキストで任意のJSを実行する — セレクターでは対応できない場合の最終手段	free

コストと制限

運用コスト

APIクォータ: 無料 — ローカル実行
呼び出しあたりのトークン: スクリーンショットはトークンを消費しません。セレクターや文字列は軽量です（1回の呼び出しにつき約100トークン）
金額: 無料
ヒント: puppeteer_evaluateで必要なデータをJSONとして正確に抽出してください — スクリーンショットを撮ってOCRするのは非効率です

セキュリティ

権限、シークレット、影響範囲

認証情報の保管： 実ユーザーの認証情報をプロンプトに入れないでください — 専用のQAアカウントを使用してください

データ送信先： ブラウザはナビゲート先のどこにでもアクセスします。MCPパブリッシャーへのデータ送信はありません

リポジトリはアーカイブ済みです — 新機能やセキュリティ修正はありません。本番環境に近い用途にはplaywright MCPへの移行を検討してください。

トラブルシューティング

よくあるエラーと対処法

Error: Element not found — 要素がまだレンダリングされていません

puppeteer_evaluate('await new Promise(r => setTimeout(r, 1000))')で短い待機を追加するか、暗黙的に待機するより具体的なセレクターを使用してください。

Chromium fails to launch on Linux/Docker — Linux/Docker環境でChromiumが起動できません

依存パッケージをインストールしてください: apt-get install -y chromium-browser、またはすべてがプリインストールされたPlaywright MCPイメージを使用してください。

Screenshots are blank — スクリーンショットが空白です

ページが読み込まれていません。ナビゲート後、既知の要素を待機してください: スクリーンショット前にポーリングループでpuppeteer_evaluate("document.querySelector('.main') !== null")を実行します。

代替案

Puppeteer 他との比較

代替案	代わりに使う場面	トレードオフ
Playwright MCP	本格的なブラウザ自動化全般 — 厳密に上位互換の選択肢	インストールサイズがやや大きいが、アクセシビリティツリーにより信頼性が向上
Firecrawl MCP	インタラクションは不要で、コンテンツ抽出だけが必要な場合	ホスト型でクレジットが必要だが、アンチボット対策の処理に優れている
browser-tools MCP	ログイン済みセッションや拡張機能を含む自分の実際のChromeを検査したい場合	Chrome拡張機能が必要。まったく異なるユースケース

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る