watch-video

Let Claude (or any MCP client) watch a video. Give it a local file or a URL (YouTube and 1,500+ other sites via yt-dlp) and it gets a timestamped transcript plus a handful of scene-selected keyframes, then drills into exact frames only when needed. No cloud transcription, no API keys.

It ships as two parts:

• video MCP server with six tools (below).

• watch-video skill that teaches Claude the cheap-first workflow: overview, then frames, then ranges.

How it works

Everything is cached under ~/.cache/video_mcp, so repeat calls are instant.

Measured on a mid-range CPU (i5-11400, no GPU): 35.7-minute local video overview in about 2.6 minutes; YouTube video with subtitles in about 7 seconds; a drill-down frame in about 0.5 seconds.

Related MCP server: ffmpeg-agent

Install

Requirements: Python 3.10+ and ffmpeg (including ffprobe) on your PATH.

pip install git+https://github.com/marwanm7moud/watch-video
# optional: Whisper for non-English videos / GPU machines
pip install "watch-video[whisper] @ git+https://github.com/marwanm7moud/watch-video"

Install ffmpeg with winget install Gyan.FFmpeg (Windows), brew install ffmpeg (macOS) or sudo apt install ffmpeg (Linux). The first transcription downloads the Parakeet model (about 650 MB).

Register the MCP server

Claude Code:

claude mcp add video --scope user -- video-mcp

Claude Desktop (claude_desktop_config.json) or any other MCP client:

{ "mcpServers": { "video": { "command": "video-mcp" } } }

If video-mcp is not on your PATH, use the full path to the executable or python -m video_mcp.server.

Install the skill

Copy the skill folder so Claude knows when and how to use the tools:

# macOS / Linux
mkdir -p ~/.claude/skills && cp -r skills/watch-video ~/.claude/skills/
# Windows (PowerShell)
Copy-Item -Recurse skills\watch-video $HOME\.claude\skills\

Then ask Claude: "Watch https://youtu.be/... and summarize it", or "At what point do they explain the stop-loss, and what does the chart show then?"

Tools

Command line

The same operations work without MCP:

video-cli overview video.mp4 --max-frames 16
video-cli frames https://youtu.be/... 12:30 13:05
video-cli range video.mp4 10:00 10:30 --count 12
video-cli search video.mp4 "stop loss"
video-cli hw

Configuration

On CPU the server runs below normal priority, one heavy job at a time, with Whisper held to AVX2, so a long transcription does not freeze your desktop.

Limitations

• Transcription is English-first. Other languages need Whisper (language="auto"), which is slow on CPU.

• Frames are sampled, not every frame is analysed; the transcript can mishear names and terms. The skill tells Claude to cite timestamps and confirm exact on-screen text with a hi-res frame.

• Use it only on videos you are allowed to access and process; respect each site's terms and copyright.

Development

pip install -e ".[dev]"
ruff check .
pytest

License

MIT. See LICENSE.