video-vision-mcp

video-vision-mcp

Claude Code があらゆる動画（ローカルファイルまたは URL）を一連のツールで分析できるようにする MCP サーバーです。

Claude は動画をネイティブに視聴できません（テキストと画像の最初のフレームのみ対応しています）。 このサーバーは、動画をサンプリングしたフレーム画像と音声の文字起こしに変換します。また、Gemini キーがある場合は、動画全体をGemini でネイティブに分析します。

このサーバーは単独で動作します。用意した動画（ローカルパスまたは直接 URL）を渡せば、あとはサーバーが処理します。Jira／Slack などには接続しません。動画が連携サービスの背後にある場合は、まずその連携サービスで取得し（ファイルにダウンロードするか、直接 URL を取得して）、その後 file_path または url をこのサーバーに渡してください。

シナリオ：Jira のバグチケットに画面録画だけがあり、テキストがありません。Jira MCP が添付ファイルを一時ファイルにダウンロード → analyze_video file_path=/tmp/bug.mp4 → フレームと文字起こし（または Gemini による分析）を確認し、バグについて推論できます。

3 段階のバックエンド（自動選択）

Tier	必要なもの	動作
1 — local（デフォルト）	なし	ffmpeg のフレームと whisper.cpp の文字起こしを使用します。無料で、完全にローカルで動作し、常に利用できます。
2 — cloud ASR	OPENAI_API_KEY または GROQ_API_KEY	フレームはローカルで処理し、文字起こしには OpenAI Whisper／Groq を使用して品質を高めます。
3 — native Gemini	GEMINI_API_KEY	Gemini が 1 回の呼び出しで動画全体（映像と音声）を取り込み、MM:SS 形式のタイムスタンプを付けて分析します。キーが設定されている場合のデフォルトです。

優先順位：Gemini > OpenAI > Groq > local. Gemini キーがあってもティア 1／2 を強制するには、VIDEO_MCP_DISABLE_GEMINI=true を設定してください。使用したバックエンドはすべての結果に表示されます。

プライバシー： ティア 1 では一切アップロードされません。ティア 2／3 では、動画コンテンツが初めてサードパーティに送信されたときに、そのセッション中に一度だけ通知が表示されます。

ツール

• analyze_video — フレーム、文字起こし、メタデータを取得します（メインツール）。frame_interval でフレーム間の秒数を指定します（デフォルトは 1.0。0.5／0.25／0.1 はより高密度、2／5 はより低密度になります）。
• get_video_transcript_only — 文字起こしテキストのみを取得します。
• extract_frames_at — 指定したタイムスタンプ（"00:42"、"1:05"、12.5）のフレームを取得します。
• list_recent_analyses — キャッシュされた分析結果と使用したバックエンドを一覧表示します。

インストール

Python ≥ 3.10 が必要です。1 回のインストールですべてが揃います。バックエンドに加え、ffmpeg と whisper.cpp の依存関係も含まれます。お使いのマシンにグローバルインストールされることはありません（brew／apt／winget も sudo も不要です）。

使用方法（推奨）

uv を使う場合、明示的にインストールする必要はありません。uvx が公開パッケージを必要に応じて実行します（Claude Code への登録を参照）。環境にインストールする場合：

uv pip install video-vision-mcp     # or: pip install video-vision-mcp

ソースからインストール（開発用）

git clone https://github.com/KitDevUA/video-vision-mcp.git
cd video-vision-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"          # all backends bundled

依存関係 — すべて自己完結

• ffmpeg / ffprobe：すでに PATH 上にある場合は、それらのシステムバイナリを使用します。ない場合は、同梱の static-ffmpeg パッケージから取得します（パッケージ独自のローカルキャッシュに一度だけ取得され、システム全体にはインストールされません）。
• whisper.cpp（ティア 1 の文字起こし）：同梱の pywhispercpp バインディングとして提供されます（ビルド済み wheel を使用し、お使いのプラットフォーム／Python 用の wheel がない場合に限りソースからビルドします）。PATH 上に whisper-cli があれば、それを使用します。
• whisper モデル：ggml モデル（デフォルトは base）は、初回の文字起こし時に Hugging Face からキャッシュへダウンロードされます。VIDEO_MCP_WHISPER_MODEL（tiny／base／small／medium／large-v3）または VIDEO_MCP_WHISPER_MODEL_PATH で変更できます。
• クラウドのみ：OPENAI_API_KEY／GROQ_API_KEY（ティア 2）または GEMINI_API_KEY（ティア 3）を設定します。この場合、whisper.cpp は呼び出されません。

設定

cp env.example .env
# edit .env — nothing is required for tier 1

すべての変数については env.example を参照してください。すべて任意です（API キーと調整用の設定です）。Tier 1 では何も必要ありません。

Claude Code に登録する

プロジェクトの .mcp.json（またはグローバル設定）に追加してください。.mcp.json.example を参照してください。

{
  "mcpServers": {
    "video-vision": {
      "command": "uvx",
      "args": ["video-vision-mcp"],
      "env": { "VIDEO_MCP_ENV": "/abs/path/to/.env" }
    }
  }
}

uvx が公開済みパッケージを自動でダウンロードして実行するため、手動でインストールする必要はありません。VIDEO_MCP_ENV は任意です（Tier 1 ではキーは不要です）。クラウドバックエンドを使用する場合は、.env のパスを指定してください。チェックアウトに対してローカル開発する場合は、代わりに "args": ["--from", "/abs/path/to/video-vision-mcp", "video-vision-mcp"] を使用してください。Claude Code を再起動すると、video-vision ツールが表示されます。

キャッシュ

結果は ~/.cache/video-vision-mcp/ に （ファイルのハッシュ、バックエンド、フレーム間隔） をキーとしてキャッシュされます。同じ動画を再分析するときは即座に結果が返され、バックエンドや間隔を切り替えても、それぞれの結果が個別に保持されます。ダウンロードした URL と whisper モデルも同じディレクトリに保存されます。VIDEO_MCP_CACHE_DIR で保存先を変更できます。

VIDEO_MCP_CACHE_TTL_HOURS（既定値は 24）より古い分析結果とダウンロード済み動画は、起動時に削除され、読み込み時にもスキップされます。永久に保持するには 0 を設定してください。whisper モデルは再ダウンロードにコストがかかるため、削除されません。

Jira、Slack などのインテグレーションと連携する

このサーバーは意図的に単独で動作する設計であり、Jira、Slack、その他のサービスと通信することはありません。動画がインテグレーションの背後にある場合は、そのインテグレーションの MCP に動画を取得させてから、結果をここに渡してください。

1. インテグレーションの MCP が添付ファイルをローカルファイルにダウンロードします（または、一般公開されている直接アクセス可能な URL を渡します。認証が必要な API URL は url では使用できません）。
2. analyze_video file_path=<downloaded file>（または url=<direct link>）を呼び出します。

これにより、認証とサービス固有のロジックを適切な場所に置き、1 つの動画ツールですべてのソースに対応できます。