Watch Video

io.github.marwanm7moudPublished by GitHub account marwanm7moudv0.2.0Updated Nov 7, 2026

Let an AI watch a video: timestamped transcript, scene-selected keyframes and exact frames. Local.

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

Local MCP server that lets an assistant watch a video from a file or URL, returning a timestamped transcript and scene-selected keyframes, then exact frames…

What you can do
  • Get an overview of a video: metadata, chapters, full transcript and contact sheets of scene-selected keyframes, optionally with on-screen text via OCR
  • Pull exact frames at given timestamps, or evenly spaced frames across a time range
  • Detect hard cuts and cuts per minute to follow pacing or screen changes
  • Read a transcript slice or search the transcript for words and phrases with timestamps
  • Check detected hardware, GPU and the transcription profile in use
When to use it
Useful when you want an assistant to summarize or answer questions about a video, including screen content such as slides, code, charts or UI, and when the video is private or you would rather not upload it to a cloud service.
Requirements
Runs locally as a Python package (Python 3.10+) with ffmpeg and ffprobe on the PATH; registered as a stdio server. No API keys or accounts. The first transcription downloads a Parakeet model of about 650 MB; Whisper and OCR are optional extras. Optional settings include VIDEO_MCP_CACHE, VIDEO_MCP_LANG, VIDEO_MCP_THREADS and VIDEO_MCP_AVX512.
Before you install
Frames and transcripts are cached under a local cache directory, so disk use grows until it is cleared. Long CPU transcriptions are heavy; VIDEO_MCP_AVX512=1 adds very heavy sustained load. Frames are sampled and transcripts can mishear names, so exact on-screen text should be confirmed. Only process videos you are allowed to access, and respect site terms and copyright.

Installation

In SourceWeft

  1. Open Watch Video in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

text
> Watch https://www.youtube.com/watch?v=jNQXAC9IVRw and tell me what he says about the elephants.
$ video-cli overview https://www.youtube.com/watch?v=jNQXAC9IVRw --max-frames 8# Me at the zooduration: 00:19transcript: platform-subs:en, language=en, 6 segments, took 0.4skeyframes: 3 scene-selected at 00:00, 00:05, 00:11total time: 6.7s
## Transcript[00:01] All right, so here we are, in front of the elephants[00:05] the cool thing about these guys is that they have really... really really long trunks and that's cool[00:16] and that's pretty much all there is to sayIMAGE: ~/.cache/video_mcp/Youtube_jNQXAC9IVRw/sheets_8/sheet_01.jpg
Claude: He stands in front of the elephants (00:01) and says the cool thing about them istheir really long trunks (00:05). That is the whole video (00:16).

Why this one

watch-videoCloud video APIs (e.g. Gemini)Transcript-only tools
Sees the screen (code, slides, charts, UI)Yes: keyframes, hi-res frames, OCRYesNo
Runs locally, nothing uploadedYesNo: the video goes to the providerVaries
API key or accountNoneRequired, billed per useVaries
Videos without captionsLocal Parakeet / WhisperYesOften fails
Token cost of the visual pass~20 frames per contact sheet (cost of ~1.5 images)Billed by video lengthNone (no visuals)
Private recordings (meetings, bug repros)Safe: never leave the machineUploadedVaries

It ships as two parts:

  • video MCP server with seven tools (below).
  • watch-video skill that teaches Claude the cheap-first workflow: overview, then frames, then ranges.

How it works

StepWhat happens
TranscriptPlatform subtitles if the video has them (seconds), else Parakeet TDT 0.6B v3 (int8, CPU, 25 European languages), else faster-whisper large-v3-turbo (other languages, GPU or language="auto").
KeyframesDecodes only keyframes at thumbnail size, drops repeats and static slides, then fills the largest time gaps. The selection adapts to how much the video changes (screencast vs. action).
Contact sheetsLabelled frames tiled into grids: about 20 frames for the token cost of 1.5 full frames. Black bars are cropped automatically.
Drill-downget_frames seeks to exact timestamps at 1280 px (readable code and charts). For URLs it seeks into the stream without downloading the whole video.

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.

Install

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

Claude Code: one command (plugin)

Installs the MCP server and the skill together. Needs uv for uvx.

text
/plugin marketplace add marwanm7moud/watch-video/plugin install watch-video@watch-video

Any agent: package, server, skill

bash
pipx install watch-video-mcp          # or: uv tool install watch-video-mcp / pip install watch-video-mcp# optional extras: Whisper (non-European languages / GPU) and OCR (on-screen text as text)pipx install "watch-video-mcp[whisper,ocr]"# latest from GitHub instead of PyPI:pip install git+https://github.com/marwanm7moud/watch-video

No install needed to try the CLI: uvx --from watch-video-mcp video-cli hw.

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:

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

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

json
{ "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

The skill works with or without the MCP server: it falls back to video-cli and installs it on first use. Copy the skill folder so your agent knows when and how to use the tools:

bash
# macOS / Linuxmkdir -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

ToolUse
video_overview(source, max_frames=40, ocr=False)Start here: metadata, chapters, full transcript, contact sheets. ocr=True adds on-screen text.
get_frames(source, timestamps, hi_res=True)Exact frames ("12:30", "1:02:05" or seconds), up to 20.
scan_range(source, start, end, count=12)Evenly spaced frames in one sheet, to follow motion or a demo.
find_cuts(source, start, end, threshold=0.2)Hard cuts (shot or screen changes) and cuts per minute, for pacing.
get_transcript(source, start, end)Transcript slice.
search_transcript(source, query)Timestamped hits for any of the words, exact phrase first; plus on-screen text after an ocr=True overview.
check_hardware()Detected tools, GPU and the transcription profile in use.

Command line

The same operations work without MCP:

bash
video-cli overview video.mp4 --max-frames 16video-cli overview demo.mp4 --ocr          # also read code/slides on screenvideo-cli frames https://youtu.be/... 12:30 13:05video-cli range video.mp4 10:00 10:30 --count 12video-cli cuts ad.mp4                       # hard cuts + cuts per minutevideo-cli search video.mp4 "stop loss"video-cli hw

Configuration

VariableDefaultEffect
VIDEO_MCP_CACHE~/.cache/video_mcpCache directory (delete it to reclaim space).
VIDEO_MCP_LANGenDefault transcription language; auto detects it with Whisper.
VIDEO_MCP_THREADS4 (CPU)Threads for CPU transcription.
VIDEO_MCP_AVX512unsetSet to 1 to let Whisper use AVX-512 (faster, but a very heavy sustained load).

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

  • English is assumed unless you pass language. Parakeet covers 25 European languages on CPU (language="de", "fr", "es", ...). Other languages (Arabic, Chinese, Japanese, Hindi, ...) need Whisper, 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

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

License

MIT. See LICENSE.

Source: README.md at commit 399bda3

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package type cannot run in the sandbox.

Version history

1
  1. v0.2.0LatestOct 31, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts