Video Vision MCP

What video-vision-mcp does

The video-vision-mcp MCP server gives Claude Code tools for inspecting video content through frames, transcripts, and metadata. Inputs can be a local file path or a direct URL. The main analysis returns sampled images, transcript text, and metadata; separate tools support transcript-only extraction and frame capture at selected timestamps.

The project is standalone. It does not retrieve attachments from Jira, Slack, or other services itself. If another integration can download a video, pass the resulting local path to this server. A direct, publicly reachable URL can also be supplied, but an authenticated API URL is not supported as a fetchable video source.

How it works

Processing is selected automatically from the available configuration. With no credentials, the local tier uses ffmpeg for frame extraction and whisper.cpp for transcription. This tier does not upload video content. An OpenAI or Groq API key keeps frame processing local while moving speech recognition to the corresponding cloud Whisper service. A Gemini API key enables native whole-video analysis, combining visual and audio interpretation in one request and returning MM:SS timestamps.

Backend priority is Gemini, then OpenAI, then Groq, then local processing. Set VIDEO_MCP_DISABLE_GEMINI=true to prevent Gemini from being selected when its key is present. Results identify which backend was used. Analyses are cached under ~/.cache/video-vision-mcp/ using the file hash, backend, and frame interval as the cache key.

Setup and configuration

Python 3.10 or newer is required. The published package can be run with uvx video-vision-mcp, or installed with pip or uv. Claude Code registers it as a stdio MCP process in .mcp.json; the example configuration uses uvx and the video-vision-mcp package name. An optional VIDEO_MCP_ENV setting can point to an environment file.

No environment variable is required for the local tier. Optional settings include OPENAI_API_KEY, GROQ_API_KEY, and GEMINI_API_KEY. Local transcription uses the base Whisper model by default; VIDEO_MCP_WHISPER_MODEL or VIDEO_MCP_WHISPER_MODEL_PATH can change the model selection. VIDEO_MCP_CACHE_DIR changes the cache location, and VIDEO_MCP_CACHE_TTL_HOURS controls cleanup of cached analyses and downloaded videos.

The package supplies or uses local ffmpeg and whisper.cpp dependencies. Whisper models are downloaded into the cache on first use. Cloud tiers do not invoke whisper.cpp.

Tools and capabilities

• analyze_video returns frames, transcript text, and metadata. Its frame_interval parameter controls the number of seconds between sampled frames.
• get_video_transcript_only returns transcript text without the frame analysis.
• extract_frames_at captures frames at specified timestamps, including values such as 00:42, 1:05, and 12.5.
• list_recent_analyses lists cached analyses and the backend used for each one.

Limitations and notes

The video-vision-mcp MCP server is intended for Claude Code, and the supplied registration instructions target Claude Code configuration. It does not replace an integration that must authenticate with Jira, Slack, or another service. Those systems must first provide a downloaded file or a direct public URL.

Cloud processing sends video-related content to the selected third party, and the server prints a one-time session notice when this occurs. Local processing avoids those uploads but depends on the local ffmpeg and Whisper workflow. Cached analyses and downloaded videos are pruned after 24 hours by default; setting VIDEO_MCP_CACHE_TTL_HOURS=0 keeps them, while Whisper models are not pruned.

Getting started with this video-vision-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.