YouTube Video Analyzer 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 を返します。

Related MCP server: YT-NINJA

要件

• Node.js 20 以降。

• Gemini API キー。

• オプション: メタデータ検索用の YouTube Data API キー。

• オプション(長時間動画の最適なサポート用): yt-dlp と ffmpeg。

クイックスタート

MCP クライアントから npx で公開パッケージを直接使用します:

{
  "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 は必須です。YOUTUBE_API_KEY は get_youtube_video_metadata にのみ必要です。

グローバルセットアップ

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

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

その後、MCP クライアントで次を使用できます:

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

パッケージ

このリポジトリは小さな npm ワークスペースです:

• @ludylogs/video-analysis-core: packages/video-analysis-core にある再利用可能なトランスポート非依存の動画分析ロジック。

• @ludylogs/youtube-video-analyzer-mcp: リポジトリルートにある MCP stdio サーバーアダプター。

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

ローカル開発

npm install
npm run build
npm test
npm start

ローカル実行用に .env を .env.example からコピーします:

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 を参照してください。