youtube-video-analyzer

YouTube 動画アナライザー MCP

Google Gemini を使って、一般公開されている YouTube 動画を分析する MCP stdio サーバーです。

MCP 対応クライアントから利用して、動画の要約、タイムスタンプ付きのインサイトの抽出、音声コンテンツの分析、メタデータの確認、長時間の VOD の処理、再利用可能な長時間動画セッションを使った追加質問ができます。

できること

• Gemini で一般公開されている YouTube 動画を分析します。
• 音声を重視した指示で、音声中心の動画を分析します。
• YouTube Data API を使って、正規化された YouTube メタデータを取得します。
• yt-dlp と ffmpeg を使って、YouTube 動画から高解像度の JPEG フレームを抽出します。
• 必須の MCP タスクを通じて、長時間の動画や VOD を分析します。
• MCP タスクに対応していないクライアント向けに、互換性のあるバックグラウンドジョブを通じて長時間の動画や VOD を分析します。
• 長時間動画セッションを再利用して追加質問に対応します。
• ローカルのダウンロードツールを利用できない場合は、URL のチャンク分割にフォールバックします。
• カスタムのレスポンススキーマを指定すると、構造化 JSON を返します。

必要条件

• Node.js 20 以降。
• Gemini API キー。
• 任意：メタデータの検索に使う YouTube Data API キー。
• 任意（長時間動画を最適にサポートする場合）：yt-dlp と ffmpeg。

クイックスタート

npx を使って、MCP クライアントから公開パッケージを直接実行します。

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "npx",
      "args": ["-y", "@ludylops/youtube-video-analyzer-mcp"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "YOUTUBE_API_KEY": "optional_youtube_key_here"
      }
    }
  }
}

GEMINI_API_KEY は必須です。get_youtube_video_metadata にのみ YOUTUBE_API_KEY が必要です。

グローバルセットアップ

パッケージをグローバルにインストールして、再利用可能な設定を保存することもできます。

npm install -g @ludylops/youtube-video-analyzer-mcp
youtube-video-analyzer-mcp setup

その後、MCP クライアントでは次のように利用できます。

{
  "mcpServers": {
    "youtube-analyzer": {
      "command": "youtube-video-analyzer-mcp"
    }
  }
}

パッケージ

このリポジトリは、小規模な npm ワークスペースです。

• @ludylops/video-analysis-core：packages/video-analysis-core にある、トランスポートに依存しない再利用可能な動画分析ロジックです。
• @ludylops/youtube-video-analyzer-mcp：リポジトリのルートにある MCP stdio サーバーアダプターです。

MCP サーバーはコアパッケージに依存しています。そのため、SaaS アプリ、CLI、スキル、その他の統合では、MCP に依存せず同じ分析ロジックを再利用できます。

ローカル開発

npm install
npm run build
npm test
npm start

ローカルで実行する場合は、.env.example を .env にコピーしてください。

GEMINI_API_KEY=your_gemini_api_key_here
YOUTUBE_API_KEY=your_youtube_api_key_here
GEMINI_MODEL=gemini-2.5-pro
YT_DLP_PATH=yt-dlp
MCP_LOG_LEVEL=warn

ツール

• get_youtube_analyzer_capabilities：長時間動画の分析戦略に関するローカル環境の対応状況を確認します。
• get_youtube_video_metadata：一般公開されている YouTube 動画の正規化済みメタデータを取得します。
• get_youtube_video_frame：タイムスタンプに対応する高解像度の JPEG フレームを抽出します。抽出前に Gemini でタイムスタンプを調整することもできます。
• analyze_youtube_video：短い動画や、範囲を指定したクリップを分析します。
• analyze_youtube_video_audio：音声を重視した指示で、音声中心の動画を分析します。
• analyze_long_youtube_video：必須の MCP タスクとして、長時間の動画や VOD を分析します。
• start_long_youtube_analysis：バックグラウンドの長時間動画ジョブを開始し、jobId を返します。
• get_long_youtube_analysis_status：バックグラウンドの長時間動画ジョブの状態を確認します。
• get_long_youtube_analysis_result：完了したバックグラウンドの長時間動画ジョブの結果を取得します。
• cancel_long_youtube_analysis：バックグラウンドの長時間動画ジョブをキャンセルします。
• continue_long_video_analysis：必須の MCP タスクとして、以前の長時間動画セッションについて追加質問します。

入力、分析戦略、使用例の詳細は、docs/tools.md を参照してください。

長時間の動画

VOD や長時間の動画では、まず get_youtube_analyzer_capabilities を呼び出してください。

ネイティブの長時間動画ツールには、MCP タスクの実行が必要です。クライアントが 120 秒などの固定タイムアウトを設けた同期ツール呼び出ししかサポートしていない場合は、互換性のあるジョブワークフローを使用してください。start_long_youtube_analysis を実行し、get_long_youtube_analysis_status でポーリングしてから、get_long_youtube_analysis_result を取得します。analyze_youtube_video を使用して、範囲を絞った短い区間を分析することもできます。

yt-dlp、ffmpeg、および書き込み可能な一時ディレクトリを利用できる場合は、strategy=auto または strategy=uploaded_file を指定して analyze_long_youtube_video を使用してください。この方法では、再利用可能な Gemini ファイルセッションを作成し、sessionId を返すことができます。

ローカルのダウンロードツールを利用できない場合は、strategy=url_chunks を使用してください。ローカルへのメディアのダウンロードは回避できますが、Gemini の呼び出し回数が増える場合があります。

詳しくは、docs/long-videos.md のガイド全文をお読みください。

ドキュメント

• インストール
• 設定
• ツール
• 長時間の動画
• 使用例
• トラブルシューティング
• リリースプロセス
• 変更履歴

プライバシーと制限事項

このサーバーは、YouTube の URL、プロンプト、および関連するメディアやそこから生成されたチャンクを Google Gemini に送信します。strategy=uploaded_file を指定した場合、ローカルツールが一時メディアをダウンロードしてから Gemini にアップロードすることがあります。get_youtube_video_frame は、一時的な高画質の動画区間をダウンロードし、正確な JPEG フレームを返します。タイムスタンプの調整が要求された場合、Gemini はタイムスタンプの選択にのみ使用され、画像ピクセルの生成には使用されません。strategy=url_chunks を指定した場合、サーバーはローカルへのメディアのダウンロードを回避しますが、Gemini の呼び出し回数が増えることがあります。

非公開、削除済み、年齢制限付き、メンバー限定、DRM で保護された、または地域制限された動画は、YouTube と Gemini のアクセス状況によっては処理に失敗することがあります。ユーザーは、YouTube の規約、Gemini API の規約、著作権に関する規則、および現地の法律を遵守する責任があります。

プロジェクト構成

• packages/video-analysis-core/src：再利用可能な動画分析コア。
• src/server.ts：MCP サーバーとツールの登録。
• src/mcp-server-main.ts：stdio トランスポートのエントリーポイント。
• src/platform-runtime：MCP サーバーが使用するランタイムアダプター。
• bin/youtube-video-analyzer-mcp.js：CLI ラッパーとセットアップフロー。
• src/test：テストスイート。

コントリビューション

コントリビューションを歓迎します。まず CONTRIBUTING.md を確認し、変更を提出する前に npm test を実行してください。また、ユーザーに見える動作を変更する場合は、CHANGELOG.md を更新してください。

ライセンス

MIT です。詳しくは LICENSE をご覧ください。