guimatheus92/mcp-video-analyzer

Turn any video — YouTube, Instagram, TikTok, Loom, X, Vimeo, direct links, local files — into transcripts, key frames, OCR text, and metadata for AI agents.
No existing video MCP combines **transcripts + visual frames + metadata** in one tool. This one does — across Loom, the major yt-dlp platforms (YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook), direct video URLs, and local files.
> **Want a full pipeline, not just a tool?** social-knowledge-base is built on top of this server — it downloads whole Instagram creator accounts (reels, stories, highlights), transcribes them, and turns the result into a searchable, RAG-queryable knowledge base with AI-generated notes. Use this MCP when you want per-video analysis inside an agent; use social-knowledge-base when you want to archive and query an entire account.
Installation
Prerequisites
- **Node.js 22.12+** — required to run the server via npx
- **yt-dlp** — **required** for YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook URLs; optional for everything else (improves Loom download quality). Install with pip install yt-dlp
- **Chrome/Chromium** (optional) — fallback for frame extraction if yt-dlp is unavailable
> Without yt-dlp or Chrome, direct URLs and local files still get frames — the bundled ffmpeg-static does the extraction, and Loom falls back to its own CDN download. Platform URLs (YouTube etc.) degrade to a clear "install yt-dlp" warning. Transcripts, metadata, and comments never require either.
There are three ways in: the **/video plugin** (Claude Code — slash command + MCP server auto-configured), a plain **MCP server** config (any MCP client), or the **portable skill + CLI** (Codex, Cursor, Copilot, and any agent with a shell — no MCP required).
Claude Code — /video plugin (recommended)
This adds the /video slash command **and** auto-registers the MCP server — no claude mcp add needed:
Other agents — Codex, Cursor, Copilot, Gemini CLI, …
Installs the video skill (Agent Skills format) into every agent detected on your machine. Agents without the MCP server configured fall back to the bundled CLI automatically — zero configuration.
Claude Code (MCP only)
Then restart Claude Code or start a new conversation.
VS Code / Cursor
Add to your MCP settings file:
- **VS Code**: File → Preferences → Settings → search "MCP" or edit ~/.vscode/mcp.json / %APPDATA%\Code\User\mcp.json (Windows)
- **Cursor**: Settings → MCP Servers → Add
Then reload the window (Ctrl+Shift+P → "Developer: Reload Window").
Claude Desktop
Add to your Claude Desktop config file:
- **macOS**: ~/Library/Application Support/Claude/claude_desktop_config.json
- **Windows**: %APPDATA%\Claude\claude_desktop_config.json
Then restart Claude Desktop.
CLI (one-shot, no MCP client)
The same engine is exposed as a one-shot command — this is what the video skill uses on agents without MCP, and it works standalone in any terminal:
stdout is a single JSON document — metadata, transcript, ocrResults, timeline, warnings, frameCount, and frames as { time, filePath, mimeType } entries pointing at JPEG key frames copied to --out (default: the per-user cache dir — %LOCALAPPDATA% on Windows, ~/Library/Caches on macOS, $XDG_CACHE_HOME or ~/.cache on Linux — under mcp-video-analyzer/ /; set MCP_CACHE_DIR to an absolute path to relocate it). Unlike the temp dir this used to live in, nothing reaps that location, so frames persist until you delete them — the directories are created 0700. Progress streams on stderr, so stdout can be piped straight into a JSON parser. Partial failures land in warnings with exit code 0; only hard failures exit 1.
| Flag | Description |
|------|-------------|
| --detail | brief (metadata + transcript, no frames), standard (default), detailed |
| --max-frames | Max key frames, 1–60 (default adapts to duration) |
| --max-width | Width cap for emitted frames (default 800, or MCP_FRAME_MAX_WIDTH); 0 keeps the source resolution — see Frame size |
| --fields | Output filter — comma-separated subset: metadata,transcript,frames,comments,chapters,ocrResults,timeline,aiSummary. Filters the emitted JSON only; use --detail brief to actually skip download/frame extraction |
| --force-refresh | Bypass the cache and re-analyze |
| --ocr-language | Tesseract languages (default eng+por) |
| --model / --language | Whisper overrides for the transcription fallback |
| --out | Where frame images are copied |
Run with no arguments (npx mcp-video-analyzer@latest) to start the MCP stdio server — the CLI is purely additive.