Video Understanding MCP

Video Understanding MCP

AI エージェントが動画を視聴して、何が映っているか、何が話されているか、画面にどのテキストが表示されているか、そしてそれがいつ起きるかについて質問に答えられる MCP サーバーです。ゲートウェイ経由で提供される Gemini モデルなど、動画を受け付けるモデルを使用する OpenAI 互換のチャット補完エンドポイントで動作します。

TikTok、YouTube、X の投稿 URL、スクレイパーから取得した直接メディア URL、またはローカルファイルと質問を渡します。動画をダウンロードして縮小し、エンドポイントに送信すると、構造化された回答が返されます。

{
  "answer": "The coach demonstrates three squat variations and warns against letting the knees cave in.",
  "summary": "A short workout tutorial showing bodyweight squats with form cues.",
  "speech": {
    "present": true,
    "language": "en",
    "transcript": "Keep your chest up and push through your heels..."
  },
  "on_screen_text": ["3 x 12 reps", "Rest 60s"],
  "timeline": [{ "start": 12.0, "description": "Switches to jump squats" }],
  "analysis": {
    "configuredModel": "your-model",
    "reportedModel": "gemini-...",
    "usage": { "promptTokens": 5400, "completionTokens": 480 },
    "sourceDurationSeconds": 58.4,
    "analyzedRange": { "start": 0, "end": 58.4 },
    "partFormat": "image_url",
    "warnings": []
  }
}

要件

• Node.js 22.21.0 以降。
• ffprobe を含む ffmpeg（必須）。macOS：brew install ffmpeg。Debian/Ubuntu：sudo apt-get install ffmpeg。Windows：winget install ffmpeg。
• yt-dlp（任意。TikTok や YouTube のリンクなど、ページ URL の場合にのみ必要）。macOS：brew install yt-dlp。その他：pipx install yt-dlp。
• OpenAI 互換のエンドポイントと、動画入力を受け付けるモデル。

get_server_info ツールで、サーバーが検出した内容を確認できます。

セットアップ

MCP クライアントにサーバーを追加します。たとえば、JSON で設定するクライアントの場合：

{
  "mcpServers": {
    "video-understanding": {
      "command": "npx",
      "args": ["-y", "@granitebps/video-understanding-mcp"],
      "env": {
        "VIDEO_BASE_URL": "https://your-endpoint.example/v1",
        "VIDEO_MODEL": "your-video-capable-model",
        "VIDEO_API_KEY": "your-endpoint-api-key"
      }
    }
  }
}

サーバーは、作業ディレクトリにある .env ファイルも読み込みます。.env.example を参照してください。

ツール

understand_video

入力	説明
source	必須。ページ URL（yt-dlp で解決）、直接メディア URL、または許可されたディレクトリ内の絶対ローカルパス。
headers	任意。スクレイパーから返された Referer や Cookie など、直接メディア URL に対するリクエストヘッダー。送信先はその URL のホストに限られます。
question	任意。調べたい内容。指定しない場合は、全般的な説明が返されます。
start_seconds, end_seconds	任意。解析する元動画の範囲。時間制限を超える動画では指定が必要です。また、短い範囲を指定すると、ワークアウトのような動きの速い映像をより詳しく確認できます。
fps	任意。フレームサンプリングのヒント。対応するリクエスト形式でのみ適用されます。

結果のフィールドは上記のとおりです。timeline の時刻は、範囲を解析した場合でも、元動画の開始からの秒数です。analysis.warnings には、サーバーが調整した内容や確認できなかった内容が記載されます。

get_server_info

バージョン、エンドポイントのホストとモデル、リクエスト形式、制限、ローカルファイルのポリシー、および ffmpeg、ffprobe、yt-dlp が利用可能かどうかを表示します。API キーは表示されません。

リクエスト形式

OpenAI 互換エンドポイントでは、チャットリクエストに動画を添付する方法が統一されておらず、理解できない形式を無視しても通知しないエンドポイントもあります。エンドポイントのドキュメントに記載されている形式を VIDEO_PART_FORMAT で選択してください。

VIDEO_PART_FORMAT	リクエストパート	使用が確認されているサービス
video_url	{"type":"video_url","video_url":{"url":"data:video/mp4;base64,..."}}	OpenRouter、Alibaba Model Studio（Qwen）、Tencent TokenHub、vLLM
image_url (default)	{"type":"image_url","image_url":{"url":"data:video/mp4;base64,..."}}	OpenRouter、データ URL の MIME タイプに基づいて画像パートを変換するルーター（例：9router の Gemini パス）
file	{"type":"file","file":{"file_data":"data:video/mp4;base64,...","format":"video/mp4"}}	LiteLLM（Gemini、vLLM）
input_file	{"type":"input_file","file_data":"data:video/mp4;base64,...","mime_type":"video/mp4"}	Requesty

fps は video_url と file の場合にのみ送信されます。

エンドポイントが動画を無視した場合、モデルが作り上げた回答を返す代わりに、呼び出しは MEDIA_NOT_PROCESSED で失敗します。サーバーは、動画を含めずに同じプロンプトを並行して送信し（出力トークンは最大 16 個）、プロンプトのトークン使用量を比較してこれを検出します。これにより、エンドポイントが追加する固定のオーバーヘッドは相殺されます。この方法ではリクエスト数が 2 倍になります。トークン使用量の報告が通常と異なるエンドポイントに限り、VIDEO_VERIFY_MEDIA=false でこの機能を無効にしてください。

設定

変数	デフォルト	説明
VIDEO_BASE_URL	—	必須です。エンドポイントのベース URL。例：https://host/v1。
VIDEO_MODEL	—	必須です。モデル名またはルーターのエイリアスです。
VIDEO_API_KEY	—	Authorization: Bearer <key> として送信されます。
VIDEO_PART_FORMAT	image_url	image_url、video_url、file、または input_file です。
VIDEO_MAX_DURATION_SECONDS	300	分析する範囲の最長時間（1～7200）です。
VIDEO_MAX_UPLOAD_MB	15	インラインで送信する、準備済み動画の最大サイズ（base64 変換前、1～100）です。
VIDEO_MAX_DOWNLOAD_MB	500	ダウンロードするソースの最大サイズ（1～10000）です。
VIDEO_REQUEST_TIMEOUT_MS	180000	エンドポイントリクエストのタイムアウト（5000～900000）です。
VIDEO_MAX_CONCURRENCY	2	同時に実行する分析の数です。上限を超えた呼び出しは待機します（1～16）。
VIDEO_MAX_OUTPUT_TOKENS	8192	回答の max_tokens（256～65536）です。
VIDEO_VERIFY_MEDIA	true	エンドポイントが動画を無視したことが明らかな場合、呼び出しを失敗させます。
VIDEO_ALLOWED_DIRS	—	ローカルファイルの読み取りを許可するディレクトリ。区切り文字は :（Windows では ;）です。未設定の場合、ローカルファイルは拒否されます。
VIDEO_ALLOW_PRIVATE_NETWORK	false	ループバックアドレスおよびプライベートアドレスからのダウンロードを許可します。
VIDEO_FFMPEG_PATH	ffmpeg	ffmpeg 実行ファイルです。
VIDEO_FFPROBE_PATH	ffprobe	ffprobe 実行ファイルです。
VIDEO_YTDLP_PATH	yt-dlp	yt-dlp 実行ファイルです。

無効な値が設定されている場合、変数名を示すメッセージとともにサーバーの起動が停止します。VIDEO_BASE_URL または VIDEO_MODEL が設定されていない場合でもサーバーは起動し、understand_video は CONFIG_MISSING を返します。

呼び出しの流れ

1. 設定、ffmpeg がインストールされていること、およびベース URL が応答することを確認します。応答しない場合、何もダウンロードされる前に ENDPOINT_UNREACHABLE で呼び出しが失敗します。
2. 動画を取得します。許可されたローカルファイルを読み込むか、直接メディア URL をダウンロードするか、yt-dlp でページ URL を解決します（ダウンロード前に、長すぎる動画は拒否します）。
3. 指定された範囲を切り出し、音声をモノラル AAC にして H.264 に再エンコードします。短辺は最大 480 ピクセル（縦向きのクリップでは 480×854）とし、アップロード制限に収まるよう必要に応じて 360 ピクセルに下げます。
4. 質問とともに、インラインの base64 形式で送信し、テキストのみのベースラインリクエストも送信します。
5. 返答を検証し、分析範囲外のタイムライン上の時点を除外して、時刻を元動画の秒数に変換します。

一時ファイルは、失敗した場合やキャンセルされた場合も含め、毎回の呼び出し後に削除されます。

エラー

エラーは、たとえば [LIMIT_EXCEEDED] The analyzed range is 1500 s, over the 300 s limit ... のように、角括弧内のコードで始まり、同じコードが _meta["video-understanding-mcp/error"] に格納されます。

コード	意味
INVALID_INPUT	範囲またはソース文字列が無効です。
CONFIG_MISSING	VIDEO_BASE_URL または VIDEO_MODEL が設定されていません。
DEPENDENCY_MISSING	ffmpeg/ffprobe、またはページ URL の場合は yt-dlp がインストールされていません。
SOURCE_UNAVAILABLE	ページまたはメディア URL を取得または抽出できませんでした（リンクの期限切れ、未対応のサイト）。
SOURCE_NOT_ALLOWED	許可されたディレクトリ外のローカルファイル、またはプライベートネットワーク上のダウンロード先です。
INVALID_MEDIA	ソースにビデオストリームがありません。
LIMIT_EXCEEDED	再生時間、アップロード、またはダウンロードの制限を超えているか、エンドポイントによってサイズが大きすぎるとして拒否されました。
ENDPOINT_UNREACHABLE	設定されたベース URL に到達できません。
ENDPOINT_AUTH	エンドポイントによって API キーが拒否されました。
ENDPOINT_RATE_LIMITED	エンドポイントによってリクエストがレート制限されました。判明している場合は retryAfterSeconds が設定されます。
ENDPOINT_ERROR	成功ステータスで返されたエラーを含む、その他のエンドポイントエラーです。
TIMEOUT	エンドポイントまたはメディア処理に時間がかかりすぎました。
EMPTY_RESPONSE	モデルからテキストが返されませんでした。
MEDIA_NOT_PROCESSED	エンドポイントが動画を無視したと見られます。別の VIDEO_PART_FORMAT をお試しください。
INTERNAL_ERROR	予期しない失敗です。

プライバシーとコンテンツの権利

• 分析対象のクリップと質問は、設定したエンドポイントに送信されます。データの取り扱いに納得できるエンドポイントを使用してください。
• 送信するコンテンツをダウンロードして分析する権利を有していること、およびダウンロード元サイトの利用規約に従うことは、お客様の責任です。
• ログは、呼び出しごとに 1 行の JSON として stderr に出力されます（コード、ソースホスト、再生時間、サイズ、処理時間、トークン数）。メディア、文字起こし、回答、クエリ文字列を含む URL、ヘッダー、API キーがログに含まれることはありません。

セキュリティ

• VIDEO_ALLOW_PRIVATE_NETWORK=true が設定されていない場合、ダウンロードでは、リダイレクト先も含め、ループバック、プライベート、リンクローカルなどの非公開アドレスへのアクセスを拒否します。エンドポイント自体はローカルアドレスでもかまいません。
• ローカルファイルは、シンボリックリンクを解決したうえで、VIDEO_ALLOWED_DIRS 内からのみ読み取ります。
• 呼び出し元が指定したヘッダーは元のホストにのみ送信され、yt-dlp に渡されることはありません。
• ffmpeg と ffprobe は入力をローカルファイルとしてのみ開き、HLS などのプレイリスト形式や連結形式は拒否します。yt-dlp は --ignore-config を指定して実行されます。

脆弱性の報告については、SECURITY.md をご覧ください。

既知の制限事項

• 動画はリクエストにインラインで含めて送信されるため、各呼び出しはアップロード上限に制限されます。長い動画では start_seconds と end_seconds を使用してください。サーバーが動画を自動的に分割することはありません。
• ページ URL の場合、ネットワーク制限で確認されるのはページのホストのみです。yt-dlp はメディアサーバーに対して独自に後続のリクエストを行います。
• ルーターがプロバイダー間でフォールバックする場合、ベースラインと実際のリクエストが固定オーバーヘッドの異なるプロバイダーによって処理されることがあり、無視対象動画の判定を誤る可能性があります。応答したモデルは analysis.reportedModel で確認できます。
• リクエストを処理したアップストリームプロバイダーは、エンドポイントが報告するモデル名以外からは確認できません。
• stdio トランスポートのみを提供しています。

開発

npm ci
npm run check

npm run check は、フォーマット、リンティング、型チェック、カバレッジ付きテスト、パッケージのチェックを実行します。テストでは、偽のエンドポイント、偽の yt-dlp、ffmpeg で生成したクリップを使用するため、ffmpeg は必要ですが、ネットワーク接続や認証情報は不要です。npm run test:live は、VIDEO_LIVE_* 変数で設定した実際のエンドポイントに対するオプトインのチェックを実行します（.env.example を参照）。

CONTRIBUTING.md と RELEASE.md をご覧ください。

ライセンス

MIT