Webpage Screenshot MCP

🚀 Webpage Screenshot MCP Server

このサーバーは、Puppeteerを使用してWebページのスクリーンショットを撮影するMCP（Model Context Protocol）サーバーです。AIエージェントがWebアプリケーションを視覚的に検証し、Webアプリの生成進捗を確認できるようになります。

✨ 主な機能

• 全ページスクリーンショット：Webページ全体またはビューポートのみをキャプチャします。
• 要素スクリーンショット：CSSセレクタを使用して特定の要素をターゲットにできます。
• 複数のフォーマット：PNG、JPEG、WebPフォーマットをサポートします。
• カスタマイズ可能なオプション：ビューポートのサイズ、画像の品質、待機条件、遅延を設定できます。
• Base64エンコード：スクリーンショットをBase64エンコードされた画像として返すため、簡単に統合できます。
• 認証サポート：手動ログインとクッキーの永続化が可能です。
• デフォルトブラウザ統合：システムのデフォルトブラウザを使用して、より自然な体験を提供します。
• セッションの永続化：多段階のワークフローでもブラウザセッションを開いたままにできます。

📦 インストール

MCPをインストールしてビルドするには、以下の手順を実行します。

# リポジトリをクローンする（まだクローンしていない場合）
git clone https://github.com/ananddtyagi/webpage-screenshot-mcp.git
cd webpage-screenshot-mcp

# 依存関係をインストールする
npm install

# プロジェクトをビルドする
npm run build

MCPサーバーはTypeScriptを使用して構築され、JavaScriptにコンパイルされます。distフォルダにはコンパイルされたJavaScriptファイルが含まれています。

ClaudeまたはCursorへの追加

このMCPをClaude DesktopまたはCursorに追加するには、以下の手順を実行します。

1. Claude Desktop：

   • [設定] > [開発者]に移動します。
   • [設定を編集]をクリックします。
   • 以下を追加します。

    "webpage-screenshot": {
      "command": "node",
      "args": [
        "~/path/to/webpage-screenshot-mcp/dist/index.js"
      ]
    }
   

   • 変更を保存して、Claudeを再読み込みします。

2. Cursor：

   • Cursorを開き、[Cursor設定] > [MCP]に移動します。
   • [新しいグローバルMCPサーバーを追加]をクリックします。
   • 以下を追加します。

    "webpage-screenshot": {
      "command": "node",
      "args": ["~/path/to/webpage-screenshot-mcp/dist/index.js"]
    }
   

   • 変更を保存して、Cursorを再読み込みします。

💻 使用例

ツール

このMCPサーバーは、いくつかのツールを提供しています。

1. login-and-wait

可視のブラウザウィンドウでWebページを開き、手動でログインします。ユーザーがログインを完了するまで待機し、その後クッキーを保存します。

{
  "url": "https://example.com/login",
  "waitMinutes": 5,
  "successIndicator": ".dashboard-welcome",
  "useDefaultBrowser": true
}

• url（必須）：ログインページのURL
• waitMinutes（オプション）：ログインを待つ最大分数（デフォルト: 5）
• successIndicator（オプション）：ログイン成功を示すCSSセレクタまたはURLパターン
• useDefaultBrowser（オプション）：システムのデフォルトブラウザを使用するかどうか（デフォルト: true）

2. screenshot-page

指定されたURLのスクリーンショットを撮影し、Base64エンコードされた画像として返します。

{
  "url": "https://example.com/dashboard",
  "fullPage": true,
  "width": 1920,
  "height": 1080,
  "format": "png",
  "quality": 80,
  "waitFor": "networkidle2",
  "delay": 500,
  "useSavedAuth": true,
  "reuseAuthPage": true,
  "useDefaultBrowser": true,
  "visibleBrowser": true
}

• url（必須）：スクリーンショットを撮影するWebページのURL
• fullPage（オプション）：全ページをキャプチャするか、ビューポートのみをキャプチャするか（デフォルト: true）
• width（オプション）：ビューポートの幅（ピクセル）（デフォルト: 1920）
• height（オプション）：ビューポートの高さ（ピクセル）（デフォルト: 1080）
• format（オプション）：画像フォーマット - "png"、"jpeg"、または "webp"（デフォルト: "png"）
• quality（オプション）：画像の品質（0 - 100）、jpegとwebpにのみ適用
• waitFor（オプション）：ページが読み込まれたと見なすタイミング - "load"、"domcontentloaded"、"networkidle0"、または "networkidle2"（デフォルト: "networkidle2"）
• delay（オプション）：ページ読み込み後の追加遅延（ミリ秒）（デフォルト: 0）
• useSavedAuth（オプション）：前回のログインで保存したクッキーを使用するかどうか（デフォルト: true）
• reuseAuthPage（オプション）：既存の認証済みページを使用するかどうか（デフォルト: false）
• useDefaultBrowser（オプション）：システムのデフォルトブラウザを使用するかどうか（デフォルト: false）
• visibleBrowser（オプション）：ブラウザウィンドウを表示するかどうか（デフォルト: false）

3. screenshot-element

CSSセレクタを使用して、Webページ上の特定の要素のスクリーンショットを撮影します。

{
  "url": "https://example.com/dashboard",
  "selector": ".user-profile",
  "waitForSelector": true,
  "format": "png",
  "quality": 80,
  "padding": 10,
  "useSavedAuth": true,
  "useDefaultBrowser": true,
  "visibleBrowser": true
}

• url（必須）：WebページのURL
• selector（必須）：スクリーンショットを撮影する要素のCSSセレクタ
• waitForSelector（オプション）：セレクタが表示されるまで待つかどうか（デフォルト: true）
• format（オプション）：画像フォーマット - "png"、"jpeg"、または "webp"（デフォルト: "png"）
• quality（オプション）：画像の品質（0 - 100）、jpegとwebpにのみ適用
• padding（オプション）：要素の周りの余白（ピクセル）（デフォルト: 0）
• useSavedAuth（オプション）：前回のログインで保存したクッキーを使用するかどうか（デフォルト: true）
• useDefaultBrowser（オプション）：システムのデフォルトブラウザを使用するかどうか（デフォルト: false）
• visibleBrowser（オプション）：ブラウザウィンドウを表示するかどうか（デフォルト: false）

4. clear-auth-cookies

特定のドメインまたはすべてのドメインの保存された認証クッキーを削除します。

{
  "url": "https://example.com"
}

• url（オプション）：クッキーを削除するドメインのURL。指定されない場合は、すべてのクッキーが削除されます。

デフォルトブラウザモード

デフォルトブラウザモードを使用すると、PuppeteerのバンドルされたChromiumの代わりに、システムの通常のブラウザ（Chrome、Edgeなど）を使用できます。これは以下の場合に便利です。

1. 既存のブラウザセッションや拡張機能を使用する。
2. 保存された資格情報で手動でウェブサイトにログインする。
3. 多段階のワークフローでより自然なブラウジング体験を得る。
4. ユーザーと同じブラウザ環境でテストする。

デフォルトブラウザモードを有効にするには、ツールのパラメータでuseDefaultBrowser: trueとvisibleBrowser: trueを設定します。

デフォルトブラウザモードの動作原理

デフォルトブラウザモードを有効にすると、以下のように動作します。

1. ツールはシステムのデフォルトブラウザ（Chrome、Edgeなど）を探します。
2. ランダムなポートでリモートデバッグを有効にしてブラウザを起動します。
3. Puppeteerは独自のブラウザを起動する代わりに、このブラウザインスタンスに接続します。
4. 既存のプロファイル、拡張機能、およびクッキーはセッション中に使用可能です。
5. ブラウザウィンドウは表示されたままになり、手動で操作することができます。

このモードは、認証や複雑なユーザーインタラクションが必要なワークフローに特に有用です。

ブラウザの永続化

MCPサーバーは、複数のツール呼び出しにわたってブラウザセッションを維持することができます。

1. login-and-waitを使用すると、ブラウザセッションが開いたままになります。
2. reuseAuthPage: trueでscreenshot-pageまたはscreenshot-elementを後続で呼び出すと、同じページが使用されます。
3. これにより、再認証することなく多段階のワークフローを実行できます。

クッキー管理

訪問した各ドメインのクッキーは自動的に保存されます。

1. login-and-waitを使用した後、クッキーはホームフォルダの.mcp-screenshot-cookiesディレクトリに保存されます。
2. useSavedAuth: trueで同じドメインを再訪問すると、これらのクッキーが自動的に読み込まれます。
3. clear-auth-cookiesツールを使用してクッキーを削除することができます。

例：認証が必要なページのスクリーンショット

以下は、認証が必要なページのスクリーンショットを撮影する例です。

1. 手動ログインフェーズ

{
  "name": "login-and-wait",
  "parameters": {
    "url": "https://example.com/login",
    "waitMinutes": 3,
    "successIndicator": ".dashboard-welcome",
    "useDefaultBrowser": true
  }
}

これにより、ログインページがデフォルトブラウザで開きます。手動でログインし、完了すると（成功インジケータが検出されるか、ログインページから移動した後）、セッションクッキーが保存されます。

2. 保存されたセッションを使用してスクリーンショットを撮影

{
  "name": "screenshot-page",
  "parameters": {
    "url": "https://example.com/account",
    "fullPage": true,
    "useSavedAuth": true,
    "reuseAuthPage": true,
    "useDefaultBrowser": true,
    "visibleBrowser": true
  }
}

これにより、保存された認証クッキーを使用して、同じブラウザウィンドウでアカウントページのスクリーンショットが撮影されます。

3. 特定の要素のスクリーンショットを撮影

{
  "name": "screenshot-element",
  "parameters": {
    "url": "https://example.com/dashboard",
    "selector": ".user-profile-section",
    "useSavedAuth": true,
    "useDefaultBrowser": true,
    "visibleBrowser": true
  }
}

4. 完了後にクッキーを削除

{
  "name": "clear-auth-cookies",
  "parameters": {
    "url": "https://example.com"
  }
}

このワークフローを使用すると、通常のユーザーのように認証が必要なページと対話し、デフォルトブラウザで完全な認証フローを完了することができます。

ヘッドレスモードと可視モード

• ヘッドレスモード (visibleBrowser: false)：ユーザーの操作が不要な自動化ワークフローに適しており、高速です。
• 可視モード (visibleBrowser: true)：ブラウザウィンドウを表示し、ユーザーの操作や手動検証が可能です。useDefaultBrowser: trueを使用する場合は必須です。

プラットフォームサポート

デフォルトブラウザの検出は、以下のプラットフォームで動作します。

• macOS：Chrome、Edge、Safariを検出します。
• Windows：レジストリまたは一般的なインストールパスを介してChromeとEdgeを検出します。
• Linux：システムコマンドを介してChromeとChromiumを検出します。

トラブルシューティング

一般的な問題

1. デフォルトブラウザが見つからない：システムがデフォルトブラウザを見つけられない場合、PuppeteerのバンドルされたChromiumにフォールバックします。
2. 接続問題：ブラウザのデバッグポートへの接続に問題がある場合は、別のインスタンスがそのポートを使用していないか確認してください。
3. クッキー問題：認証が機能しない場合は、clear-auth-cookiesツールを使用してクッキーを削除してみてください。

デバッグ

問題が発生した場合、MCPサーバーはコンソールに有用なエラーメッセージを記録します。これらのメッセージをチェックしてトラブルシューティング情報を取得してください。