Webpage Screenshot MCP Server

Webpage Screenshot MCP Server

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

特長

• ページ全体のスクリーンショット：ウェブページ全体、またはビューポートのみを撮影します
• 要素のスクリーンショット：CSS セレクターを使って特定の要素を指定します
• 複数の形式：PNG、JPEG、WebP 形式に対応しています
• カスタマイズ可能なオプション：ビューポートのサイズ、画像品質、待機条件、遅延時間を設定できます
• Base64 エンコード：スクリーンショットを Base64 エンコードされた画像として返すため、簡単に統合できます
• 認証サポート：手動ログインと Cookie の永続化に対応しています
• デフォルトブラウザーとの連携：システムのデフォルトブラウザーを使用し、より自然な操作を実現します
• セッションの永続化：複数ステップのワークフローでもブラウザーセッションを開いたままにします

インストール

クイックスタート（Claude Desktop Extension）

生成された screenshot-webpage-mcp.dxt ファイルを Claude Desktop にドラッグ＆ドロップすると、自動的にインストールされます！

手動インストール

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

# Clone the repository (if you haven't already)
git clone https://github.com/ananddtyagi/webpage-screenshot-mcp.git
cd webpage-screenshot-mcp

# Install dependencies
npm install

# Build the project
npm run build

この MCP サーバーは TypeScript で構築され、JavaScript にコンパイルされます。dist フォルダーには、コンパイルされた JavaScript ファイルが格納されています。

Claude または Cursor への追加

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

1. Claude Desktop：

   • Settings > Developer に移動します
   • 「Edit Config」をクリックします
   • 以下を追加します。

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

   • 保存して Claude を再読み込みします

2. Cursor：

   • Cursor を開き、Cursor Settings > MCP に移動します
   • 「Add new global MCP server」をクリックします
   • 以下を追加します。

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

• 保存して Cursor を再読み込みします

使い方

ツール

この MCP サーバーは、複数のツールを提供します。

1. login-and-wait

手動ログイン用にウェブページを表示中のブラウザーウィンドウで開き、ユーザーがログインを完了するまで待機してから Cookie を保存します。

{
  "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（必須）：スクリーンショットを撮影するウェブページの 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（任意）：前回のログインで保存した Cookie を使用するかどうか（デフォルト：true）
• reuseAuthPage（任意）：既存の認証済みページを使用するかどうか（デフォルト：false）
• useDefaultBrowser（任意）：システムのデフォルトブラウザーを使用するかどうか（デフォルト：false）
• visibleBrowser（任意）：ブラウザーウィンドウを表示するかどうか（デフォルト：false）

3. screenshot-element

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

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

• url（必須）：ウェブページの URL
• selector（必須）：スクリーンショットを撮影する要素の CSS セレクター
• waitForSelector（任意）：セレクターが表示されるまで待機するかどうか（デフォルト：true）
• format（任意）：画像形式。「png」、「jpeg」、または「webp」（デフォルト：「png」）
• quality（任意）：画像の品質（0～100）。jpeg と webp の場合のみ適用されます
• padding（任意）：要素の周囲のパディング（ピクセル単位、デフォルト：0）
• useSavedAuth（任意）：前回のログイン時に保存した Cookie を使用するかどうか（デフォルト：true）
• useDefaultBrowser（任意）：システムのデフォルトブラウザーを使用するかどうか（デフォルト：false）
• visibleBrowser（任意）：ブラウザーウィンドウを表示するかどうか（デフォルト：false）

4. clear-auth-cookies

特定のドメインまたはすべてのドメインの保存済み認証 Cookie を消去します。

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

• url（任意）：Cookie を消去するドメインの URL。指定しない場合、すべての Cookie を消去します。

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

デフォルトブラウザーモードでは、Puppeteer に付属する Chromium の代わりに、システムの通常のブラウザー（Chrome、Edge など）を使用できます。次のような場合に便利です。

1. 既存のブラウザーセッションや拡張機能を使用する
2. 保存済みの認証情報を使って、ウェブサイトに手動でログインする
3. 複数ステップのワークフローで、より自然なブラウジング体験を得る
4. ユーザーと同じブラウザー環境でテストする

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

デフォルトブラウザーモードの仕組み

デフォルトブラウザーモードを有効にすると、次の処理が行われます。

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

このモードは、認証や複雑なユーザー操作が必要なワークフローで特に便利です。

ブラウザーの永続化

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

1. login-and-wait を使用すると、ブラウザーセッションは開いたままになります
2. 以降の screenshot-page または screenshot-element の呼び出しで reuseAuthPage: true を指定すると、同じページが使用されます
3. これにより、再認証せずに複数ステップのワークフローを実行できます

Cookie の管理

アクセスした各ドメインの Cookie は自動的に保存されます。

1. login-and-wait の使用後、Cookie はホームフォルダー内の .mcp-screenshot-cookies ディレクトリに保存されます
2. useSavedAuth: true を指定すると、同じドメインに再度アクセスしたときに、これらの Cookie が自動的に読み込まれます
3. clear-auth-cookies ツールを使って Cookie を消去できます

ワークフローの例：保護されたページのスクリーンショット

認証が必要なページのスクリーンショットを撮影するワークフローの例を示します。

1. 手動ログイン段階

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

デフォルトブラウザーでログインページが開きます。手動でログインできます。成功を示すインジケーターが検出されるか、ログインページから移動すると、セッション Cookie が保存されます。

2. 保存済みセッションを使ったスクリーンショットの撮影

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

同じブラウザーウィンドウで、保存済みの認証 Cookie を使ってアカウントページのスクリーンショットを撮影します。

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

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

4. 作業完了後の Cookie の消去

{
  "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. Cookieの問題：認証が機能しない場合は、clear-auth-cookies ツールでCookieをクリアしてみてください。

デバッグ

問題が発生すると、MCP サーバーは役立つエラーメッセージをコンソールに記録します。トラブルシューティングの情報については、これらのメッセージを確認してください。