Webpage Screenshot MCP Server

ウェブページのスクリーンショット MCP サーバー

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

特徴

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

インストール

使用法

ツール

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

1. ログインして待機する

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

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

2. スクリーンショットページ

指定された URL のスクリーンショットをキャプチャし、base64 でエンコードされた画像として返します。

• 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. スクリーンショット要素

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

• 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. 認証クッキーをクリアする

特定のドメインまたはすべてのドメインの保存された認証 Cookie をクリアします。

• 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 が自動的に保存されます。

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

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

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

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

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

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

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

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

4. 完了したらCookieを消去する

このワークフローにより、通常のユーザーと同じように保護されたページを操作でき、デフォルトのブラウザで完全な認証フローを完了できます。

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

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

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

デフォルトのブラウザ検出は次のブラウザで機能します:

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

トラブルシューティング

よくある問題

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

デバッグ

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