{
  "markdown": "# video-vision-mcp\n\n[![CI](https://github.com/KitDevUA/video-vision-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/KitDevUA/video-vision-mcp/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/video-vision-mcp)](https://pypi.org/project/video-vision-mcp/)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n<!-- mcp-name: io.github.KitDevUA/video-vision-mcp -->\n\nAn MCP server that gives Claude Code the ability to **analyze any video** —\na local file or a URL — through one set of tools.\n\nClaude can't watch video natively (only text + the first frame of an image).\nThis server converts a video into **sampled frame images + an audio transcript**,\nor — when a Gemini key is present — a **native Gemini analysis** of the whole video.\n\nIt is **standalone**: give it a ready video (a local path or a direct URL) and it\ndoes the rest. It does not connect to Jira/Slack/etc. If a video lives behind an\nintegration, fetch it with that integration first (download to a file or get a\ndirect URL), then hand the `file_path` or `url` to this server.\n\n> Scenario: a Jira bug ticket has only a screen-recording, no text. Your Jira MCP\n> downloads the attachment to a temp file → `analyze_video file_path=/tmp/bug.mp4`\n> → you see the frames + transcript (or Gemini's analysis) and can reason about the bug.\n\n## Three backend tiers (auto-selected)\n\n| Tier | Needs | What it does |\n|---|---|---|\n| **1 — local** (default) | nothing | `ffmpeg` frames + `whisper.cpp` transcript. Free, fully local, always works. |\n| **2 — cloud ASR** | `OPENAI_API_KEY` or `GROQ_API_KEY` | Local frames, but transcription via OpenAI Whisper / Groq for higher quality. |\n| **3 — native Gemini** | `GEMINI_API_KEY` | Gemini ingests the whole video (visual + audio) in one call, with MM:SS timestamps. Default when the key is set. |\n\nPrecedence: **Gemini > OpenAI > Groq > local.** Set `VIDEO_MCP_DISABLE_GEMINI=true`\nto force tiers 1/2 even with a Gemini key. The backend used is named in every result.\n\n**Privacy:** tier 1 never uploads anything. Tiers 2/3 print a one-time notice in\nthe session the first time video content is sent to a third party.\n\n## Tools\n\n- `analyze_video` — frames + transcript + metadata (the main tool). `frame_interval`\n  sets seconds between frames (default 1.0; e.g. 0.5/0.25/0.1 denser, 2/5 sparser).\n- `get_video_transcript_only` — transcript text only.\n- `extract_frames_at` — frames at specific timestamps (`\"00:42\"`, `\"1:05\"`, `12.5`).\n- `list_recent_analyses` — cached analyses + backend used.\n\n## Install\n\nRequires **Python ≥ 3.10**. A single install pulls everything — backends, plus the\nffmpeg and whisper.cpp dependencies. **Nothing is ever installed globally on your\nmachine** (no brew/apt/winget, no sudo).\n\n### Use it (recommended)\n\nWith [uv](https://docs.astral.sh/uv/) you don't install it explicitly — `uvx` runs\nthe published package on demand (see [Register in Claude Code](#register-in-claude-code)).\nTo install into an environment instead:\n\n```bash\nuv pip install video-vision-mcp     # or: pip install video-vision-mcp\n```\n\n### From source (development)\n\n```bash\ngit clone https://github.com/KitDevUA/video-vision-mcp.git\ncd video-vision-mcp\nuv venv && source .venv/bin/activate\nuv pip install -e \".[dev]\"          # all backends bundled\n```\n\n### Dependencies — fully self-contained\n\n- **ffmpeg / ffprobe**: if they are already on your `PATH`, those system binaries\n  are used. Otherwise the bundled `static-ffmpeg` package supplies them (fetched\n  once into its own local cache — never a system-wide install).\n- **whisper.cpp** (tier 1 transcription): shipped as the bundled `pywhispercpp`\n  binding (prebuilt wheels; builds from source only if no wheel exists for your\n  platform/Python). A `whisper-cli` already on `PATH` is used if present.\n- **whisper model**: the ggml model (`base` by default) downloads from Hugging\n  Face into the cache on first transcription. Override with\n  `VIDEO_MCP_WHISPER_MODEL` (`tiny`/`base`/`small`/`medium`/`large-v3`) or\n  `VIDEO_MCP_WHISPER_MODEL_PATH`.\n- **cloud-only**: set `OPENAI_API_KEY` / `GROQ_API_KEY` (tier 2) or\n  `GEMINI_API_KEY` (tier 3); whisper.cpp is then never invoked.\n\n## Configure\n\n```bash\ncp env.example .env\n# edit .env — nothing is required for tier 1\n```\n\nSee `env.example` for every variable — all optional (API keys and tuning). Tier 1\nneeds none.\n\n## Register in Claude Code\n\nAdd to your project `.mcp.json` (or global config) — see `.mcp.json.example`:\n\n```json\n{\n  \"mcpServers\": {\n    \"video-vision\": {\n      \"command\": \"uvx\",\n      \"args\": [\"video-vision-mcp\"],\n      \"env\": { \"VIDEO_MCP_ENV\": \"/abs/path/to/.env\" }\n    }\n  }\n}\n```\n\n`uvx` downloads and runs the published package automatically — no manual install\nstep. `VIDEO_MCP_ENV` is optional (tier 1 needs no keys); point it at your `.env`\nif you use the cloud backends. For local development against a checkout, use\n`\"args\": [\"--from\", \"/abs/path/to/video-vision-mcp\", \"video-vision-mcp\"]` instead.\nRestart Claude Code; the `video-vision` tools then appear.\n\n## Cache\n\nResults are cached at `~/.cache/video-vision-mcp/` keyed by **(file hash,\nbackend, frame interval)** — re-analyzing the same video is instant, and\nswitching backends or intervals keeps each result separately. Downloaded URLs and\nwhisper models live under the same dir. Override with `VIDEO_MCP_CACHE_DIR`.\n\nCached analyses and downloaded videos older than `VIDEO_MCP_CACHE_TTL_HOURS`\n(default **24**) are pruned on startup and skipped on read; set `0` to keep them\nforever. Whisper models are never pruned (expensive to re-download).\n\n## Using it with an integration (e.g. Jira, Slack)\n\nThis server is deliberately standalone — it never talks to Jira, Slack, or any\nother service. When a video lives behind an integration, let that integration's\nMCP fetch it, then pass the result here:\n\n1. The integration MCP downloads the attachment to a local file (or gives a\n   direct, publicly reachable URL — an authenticated API URL won't work with `url`).\n2. Call `analyze_video file_path=<downloaded file>` (or `url=<direct link>`).\n\nThis keeps auth and service-specific logic where it belongs, and lets one video\ntool serve every source.\n",
  "bytes": 6261,
  "sha": "d9985211e1e2eb98e4607ba8492841c16243124ddd290c1c6fdb0de9d06e429b",
  "repo_slug": "kitdevua/video-vision-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kitdevua_video_vision_mcp_287cfe2b/readme"
}