Video Screenshot MCP

🚀 ビデオスクリーンショットMCP

このツールは、Model Context Protocol (MCP) をベースにしたビデオスクリーンショットサービスです。高品質なビデオフレームの抽出や、バッチでのスクリーンショット取得機能をサポートしています。

✨ 主な機能

• 🎯 高精度なスクリーンショット: ミリ秒単位の精度でビデオフレームを抽出できます。
• 📊 バッチ処理: 一定の時間間隔でビデオ画面を一括でスクリーンショットできます。
• 🔍 ビデオ情報の取得: ビデオの詳細情報（再生時間、解像度、フレームレートなど）を取得できます。
• 🖼️ 複数の出力形式をサポート: JPG、PNG、WebP の出力形式に対応しています。
• ⚙️ 柔軟な設定: 出力品質やサイズなどのパラメータをカスタマイズできます。
• ✅ ファイルの検証: ビデオファイルの有効性を自動で検証します。
• 🚀 高性能: FFmpeg をベースにした高速なビデオ処理が可能です。

📦 インストール

MCP サービスとして使用する場合（推奨）

IDE の設定ファイルに以下の設定を追加してください。

{
  "mcpServers": {
    "video-screenshot": {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  }
}

ローカルにインストールする場合

npm install @pickstar-2002/video-screenshot-mcp

🚀 クイックスタート

IDE での設定

Cursor / VS Code

settings.json に以下を追加します。

{
  "mcp.servers": {
    "video-screenshot": {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  }
}

Claude Desktop

claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "video-screenshot": {
      "command": "npx",
      "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
    }
  }
}

基本的な使用例

設定が完了したら、AI アシスタントを使って以下のような操作ができます。

ビデオ /path/to/video.mp4 の 30 秒目の画面をスクリーンショットしてください

ビデオを 10 秒ごとにスクリーンショットし、PNG 形式で保存してください

このビデオファイルの詳細情報を取得してください

💻 使用例

基本的な使用法

# ビデオの特定の秒数の画面をスクリーンショット
ビデオ /path/to/video.mp4 の 30 秒目の画面をスクリーンショットしてください

# ビデオを一定間隔でバッチスクリーンショット
ビデオを 10 秒ごとにスクリーンショットし、PNG 形式で保存してください

# ビデオの詳細情報を取得
このビデオファイルの詳細情報を取得してください

📚 ドキュメント

🔍 get_video_info

ビデオファイルの詳細情報を取得します。

パラメータ:

• videoPath (string): ビデオファイルのパス

戻り値: 再生時間、解像度、フレームレート、コーデック形式などの情報を含むオブジェクト

📸 take_screenshot

指定された時間でビデオの 1 フレームをスクリーンショットします。

パラメータ:

• videoPath (string): ビデオファイルのパス
• timestamp (number): スクリーンショットを撮る時間（秒）
• outputPath (string): 出力ファイルのパス
• format (string, オプション): 出力形式 (jpg/png/webp)、デフォルトは jpg
• quality (number, オプション): 画像の品質 (1-100)、デフォルトは 90
• width (number, オプション): 出力幅（ピクセル）
• height (number, オプション): 出力高さ（ピクセル）

📷 batch_screenshot

一定の時間間隔でビデオ画面を一括でスクリーンショットします。

パラメータ:

• videoPath (string): ビデオファイルのパス
• interval (number): スクリーンショットの時間間隔（秒）
• startTime (number, オプション): 開始時間（秒）、デフォルトは 0
• endTime (number, オプション): 終了時間（秒）、デフォルトはビデオの終了
• maxCount (number, オプション): 最大スクリーンショット数
• outputDir (string, オプション): 出力ディレクトリ、デフォルトは ./screenshots
• prefix (string, オプション): ファイル名のプレフィックス、デフォルトは screenshot
• format (string, オプション): 出力形式、デフォルトは jpg
• quality (number, オプション): 画像の品質、デフォルトは 90
• width (number, オプション): 出力幅（ピクセル）
• height (number, オプション): 出力高さ（ピクセル）

✅ validate_video

ビデオファイルが有効で処理可能かどうかを検証します。

パラメータ:

• videoPath (string): ビデオファイルのパス

戻り値: 検証結果とエラー情報（ある場合）

🎯 使用シーン

• 📝 コンテンツ作成: ビデオのサムネイルやプレビュー画像を作成するのに便利です。
• 🎬 ビデオ分析: 重要なフレームを抽出してコンテンツ分析を行うことができます。
• 📊 品質検査: ビデオの品質やコンテンツを一括でチェックできます。
• 🔍 素材管理: ビデオライブラリのプレビュー画像を生成するのに役立ちます。
• 🎨 デザイン作業: ビデオフレームをデザイン素材として利用できます。

🛠️ トラブルシューティング

❌ 一般的な問題

問題 1: Connection closed エラー

症状: MCP サービスを使用する際に接続が閉じられるエラーが発生します。

解決策（推奨順）:

1. 🎯 最初の選択肢: @latest タグを使用していることを確認します。

   {
     "command": "npx",
     "args": ["@pickstar-2002/video-screenshot-mcp@latest"]
   }
   

2. 🔄 代替案: 特定の安定したバージョンに固定します。

   {
     "command": "npx",
     "args": ["@pickstar-2002/video-screenshot-mcp@1.1.1"]
   }
   

3. 🧹 最後の手段: npx キャッシュをクリアします。

   # npx キャッシュをクリア
   npx clear-npx-cache
   
   # または手動でキャッシュディレクトリを削除
   # Windows: %USERPROFILE%\.npm\_npx
   # macOS/Linux: ~/.npm/_npx
   

問題 2: FFmpeg が見つからない

症状: FFmpeg が利用できないまたはインストールされていないというエラーが表示されます。

解決策:

# Windows (Chocolatey を使用)
choco install ffmpeg

# macOS (Homebrew を使用)
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

問題 3: 権限エラー

症状: ビデオファイルを読み取れないまたはスクリーンショットを書き込めないエラーが発生します。

解決策:

• ビデオファイルのパスが正しく、アクセス可能であることを確認します。
• 出力ディレクトリの書き込み権限を確認します。
• Windows では管理者権限で実行する必要がある場合があります。

問題 4: ビデオ形式がサポートされていない

症状: 一部のビデオファイルを処理できません。

解決策:

• validate_video ツールを使用してファイルの有効性を確認します。
• サポートされている形式: MP4、AVI、MOV、MKV、WebM、FLV などの一般的な形式
• 特殊な形式の場合は、MP4 に変換することをお勧めします。

📋 デバッグのヒント

1. 詳細ログを有効にする: 環境変数 DEBUG=video-screenshot:* を設定します。
2. ファイルパスを確認する: 相対パスの問題を避けるために絶対パスを使用します。
3. 小さいファイルでテストする: まず小さいビデオファイルで機能をテストします。
4. エラーメッセージを確認する: エラーメッセージに含まれる具体的な指示をよく読みます。

🔧 技術詳細

システム要件

• Node.js: >= 18.0.0
• FFmpeg: システムに FFmpeg がインストールされている必要があります。
• オペレーティングシステム: Windows、macOS、Linux
• メモリ: 利用可能なメモリは少なくとも 512MB を推奨します。

📄 ライセンス

このプロジェクトは MIT ライセンス の下で公開されています。

🤝 貢献

Issue や Pull Request の投稿を歓迎します！

開発環境のセットアップ

# リポジトリをクローン
git clone https://github.com/pickstar-2002/video-screenshot-mcp.git
cd video-screenshot-mcp

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

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

# テストを実行
npm test

📞 連絡先

問題や提案がある場合は、以下の方法で連絡してください。

微信: pickstar_loveXX

⭐ このプロジェクトが役に立った場合は、Star をしてサポートしてください！