A Fast Website Screenshot MCP

@just-every/mcp-screenshot-website-fast

Web ページを高速かつ効率的にスクリーンショットで撮影します。CLI コーディングツール向けに最適化されており、ページ全体を最適な処理のために 1072x1072 のチャンクへ自動的に分割します。

概要

AI ビジョンのワークフロー向けに特化して構築されたこのツールは、Claude Vision API やその他の AI モデルで最適に処理できるよう、解像度の自動制限とタイル分割を行い、高品質なスクリーンショットを撮影します。最大限の互換性を確保するため、スクリーンショットを 1072x1072 ピクセル（1.15 メガピクセル）に最適化します。

特長

• 📸 Puppeteer のヘッドレスブラウザーを使用した高速なスクリーンショット撮影
• 🎯 自動解像度制限によりClaude Vision 向けに最適化（最適な 1.15 メガピクセルを実現する 1072x1072）
• 🔲 自動タイル分割 - ページ全体を自動的に 1072x1072 のタイルに分割します
• 🎬 スクリーンキャスト撮影 - 設定可能な間隔で、時間経過に沿って一連のスクリーンショットを記録します
• 🔄 常に最新のコンテンツ - キャッシュを使用せず、最新のスクリーンショットを取得します
• 📱 レスポンシブテスト向けにビューポートを設定可能
• ⏱️ 動的なコンテンツ向けの待機方法（networkidle、カスタム遅延）
• 📄 ページ全体のスクリーンショットを取得できるページ全体の撮影（デフォルト）
• 🎥 アニメーション WebP エクスポート - スクリーンキャストを高品質なアニメーション WebP ファイルとして保存します
• 💉 JavaScript の挿入 - スクリーンキャスト撮影前にカスタム JS を実行します
• 📦 npm のインストールを高速化する最小限の依存関係
• 🔌 AI ワークフローにシームレスに統合できるMCP 連携
• 🪟 npm でインストールした MCP を利用できるWindows 対応ランチャー
• 🔋 効率的なリソース使用 - 60 秒間操作がないと、ブラウザーを自動的に終了します
• 🧹 メモリ管理 - メモリリークを防ぐため、スクリーンショットの撮影後にページを閉じます

インストール

Claude Code

claude mcp add screenshot-website-fast -s user -- npx -y @just-every/mcp-screenshot-website-fast

VS Code

code --add-mcp '{"name":"screenshot-website-fast","command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}'

Cursor

cursor://anysphere.cursor-deeplink/mcp/install?name=screenshot-website-fast&config=eyJzY3JlZW5zaG90LXdlYnNpdGUtZmFzdCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqdXN0LWV2ZXJ5L21jcC1zY3JlZW5zaG90LXdlYnNpdGUtZmFzdCJdfX0=

JetBrains IDEs

設定 → ツール → AI アシスタント → Model Context Protocol (MCP) → 追加

「As JSON」を選択して貼り付けます：

{"command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}

Raw JSON（あらゆる MCP クライアントで動作）

{
  "mcpServers": {
    "screenshot-website-fast": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-screenshot-website-fast"]
    }
  }
}

これをクライアントの mcp.json（例：.vscode/mcp.json、~/.cursor/mcp.json、または Claude 用の .mcp.json）に追加します。

前提条件

• Node.js 20.x 以上
• npm または npx
• Chrome/Chromium（Puppeteer によって自動的にダウンロードされます）

クイックスタート

MCP サーバーの使用方法

IDE にインストールすると、次のツールを使用できます：

利用可能なツール

• take_screenshot - Web ページの高品質なスクリーンショットを撮影します

  • パラメーター：
    • url（必須）：撮影する HTTP/HTTPS URL
    • width（任意）：ビューポートの幅（ピクセル単位、最大 1072、デフォルト：1072）
    • height（任意）：ビューポートの高さ（ピクセル単位、最大 1072、デフォルト：1072）
    • fullPage（任意）：タイリングを使用してページ全体のスクリーンショットを撮影します（デフォルト：true）
    • waitUntil（任意）：イベントまで待機します：load、domcontentloaded、networkidle0、networkidle2（デフォルト：domcontentloaded）
    • waitFor（任意）：追加の待機時間（ミリ秒単位）
    • directory（任意）：スクリーンショットの保存先ディレクトリ。base64 画像の代わりにファイルパスを返します

• capture_selector - CSS セレクターに一致する特定の DOM 要素のスクリーンショットを撮影します

  • パラメーター：
    • url（必須）：撮影する HTTP/HTTPS URL
    • selector（必須）：撮影する要素の CSS セレクター
    • width（任意）：ビューポートの幅（ピクセル単位、最大 1072、デフォルト：1072）
    • height（任意）：ビューポートの高さ（ピクセル単位、最大 1072、デフォルト：1072）
    • waitUntil（任意）：イベントまで待機します：load、domcontentloaded、networkidle0、networkidle2（デフォルト：domcontentloaded）
    • waitForMS（任意）：追加の待機時間（ミリ秒単位）
    • selectorTimeoutMS（任意）：セレクターが表示されるまで待機する時間。時間内に表示されない場合は失敗します（デフォルト：5000）

使用例

デフォルトの使い方（base64 画像を返します）：

take_screenshot(url="https://example.com")

ディレクトリに保存（ファイルパスを返します）：

take_screenshot(url="https://example.com", directory="/path/to/screenshots")

特定の要素を撮影：

capture_selector(url="https://example.com", selector="#main")

directory パラメーターを使用する場合：

• スクリーンショットはタイムスタンプ付きの PNG ファイルとして保存されます
• base64 データの代わりにファイルパスが返されます
• タイル状のスクリーンショットの場合、各タイルは個別のファイルとして保存されます
• ディレクトリが存在しない場合は自動的に作成されます

take_screencast

時間の経過に合わせて一連のスクリーンショットを撮影し、スクリーンキャストを作成します。ビューポートの最上部のタイル（1072x1072）のみを撮影します。

パラメーター

• url（必須）：撮影する URL
• duration（任意）：合計時間（秒単位、デフォルト：10）
• interval（任意）：スクリーンショット間の間隔（秒単位、デフォルト：2）
• jsEvaluate（任意）：開始時に実行する JavaScript コード
• waitUntil（任意）：待機方法：'load'、'domcontentloaded'、'networkidle0'、'networkidle2'
• waitForMS（任意）：開始前の追加待機時間
• directory（任意）：アニメーション WebP としてディレクトリに保存します（1 秒ごとに撮影）

使用例

基本的なスクリーンキャスト（10 秒間に 5 フレーム）：

take_screencast(url="https://example.com")

タイミングを指定：

take_screencast(url="https://example.com", duration=15, interval=3)

JavaScript の実行を含む場合：

take_screencast(
  url="https://example.com",
  jsEvaluate="document.body.style.backgroundColor = 'red';"
)

アニメーション WebP として保存：

take_screencast(url="https://example.com", directory="/path/to/output")

directory パラメーターを使用する場合：

• 1 秒間隔のアニメーション WebP が作成されます
• 個々のフレームも PNG ファイルとして保存されます
• アニメーションはデフォルトで無限にループします
• WebP は優れた画質を提供します：
  • フルカラーに対応（256 色の制限なし）
  • Web アニメーションに適した効率的な圧縮
  • グラデーション背景や滑らかなアニメーションに最適
  • GIF よりも画質が高く、ファイルサイズも小さい

開発での使用方法

インストール

npm install
npm run build

スクリーンショットを撮影

# Full page with automatic tiling (default)
npm run dev capture https://example.com -o screenshot.png

# Viewport-only screenshot  
npm run dev capture https://example.com --no-full-page -o screenshot.png

# Wait for specific conditions
npm run dev capture https://example.com --wait-until networkidle0 --wait-for 2000 -o screenshot.png

CLI オプション

• -w, --width <pixels> - ビューポートの幅（最大 1072、デフォルト：1072）
• -h, --height <pixels> - ビューポートの高さ（最大 1072、デフォルト：1072）
• --no-full-page - ページ全体の撮影とタイリングを無効にします
• --wait-until <event> - イベントまで待機します：load、domcontentloaded、networkidle0、networkidle2
• --wait-for <ms> - 追加の待機時間（ミリ秒単位）
• -o, --output <path> - 出力ファイルのパス（タイル状の出力には必須）

自動再起動機能

MCP サーバーには、信頼性を高めるための自動再起動機能がデフォルトで含まれています。

• サーバーがクラッシュした場合、自動的に再起動します
• 未処理の例外や Promise の拒否を処理します
• 指数バックオフを実装しています（1 分間に最大 10 回試行）
• 監視用にすべての再起動試行をログに記録します
• シャットダウンシグナル（SIGINT、SIGTERM）を適切に処理します

自動再起動を無効にして開発／デバッグするには：

# Run directly without restart wrapper
npm run serve:dev

アーキテクチャ

mcp-screenshot-website-fast/
├── src/
│   ├── internal/       # Core screenshot capture logic
│   ├── utils/          # Logger and utilities
│   ├── index.ts        # CLI entry point
│   ├── serve.ts        # MCP server entry point
│   └── serve-restart.ts # Auto-restart wrapper

開発

# Run in development mode
npm run dev capture https://example.com -o screenshot.png

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

このツールを選ぶ理由

AI ビジョンのワークフロー向けに特化して構築されています。

1. Claude Vision API 向けに最適化 - 解像度を 1072x1072 ピクセル（1.15 メガピクセル）に自動で制限します
2. 自動タイル分割 - ページ全体を AI 処理に最適なサイズのチャンクに分割します
3. 常に最新 - キャッシュしないため、最新のコンテンツを取得できます
4. MCP ネイティブ - AI 開発ツールと第一級の統合を実現します
5. シンプルな API - スクリーンショットを取得するための、明快で使いやすいインターフェースです

コントリビューション

コントリビューションを歓迎します。次の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新しい機能のテストを追加します
4. プルリクエストを送信します

トラブルシューティング

Puppeteer の問題

• Chrome/Chromium をダウンロードできることを確認してください
• ファイアウォールの設定を確認してください
• PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true を設定し、カスタムの実行ファイルを指定してみてください

スクリーンショットの品質

• ビューポートのサイズを調整してください
• 適切な待機方法を使用してください
• サイトで認証が必要かどうか確認してください

タイムアウトエラー

• --wait-for フラグで待機時間を延長してください
• 別の --wait-until 方法を使用してください
• サイトにアクセスできるか確認してください

ライセンス

MIT