video-brief-mcp

An MCP server that turns a screen-recorded walkthrough — the "here's my feedback, let me show you" video a client or PM sends — into something a coding assistant can actually read: a timestamped transcript, frames, scene changes, and slices that pair what was said with what was on screen.

Everything runs locally: ffmpeg for video, openai-whisper for speech. Nothing is uploaded anywhere.

Tools

Times accept seconds, MM:SS or HH:MM:SS. All tools are read-only except brief_export.

Related MCP server: vidlizer

Requirements

• macOS or Linux with ffmpeg / ffprobe on PATH (brew install ffmpeg)

• Python 3 with openai-whisper (pip install openai-whisper); the first run of a model downloads it to ~/.cache/whisper

Setup

npm install && npm run build
claude mcp add video-brief --scope user -- node /absolute/path/to/video-brief-mcp/dist/index.js

Optional environment: VIDEO_BRIEF_MODEL (default small), VIDEO_BRIEF_LANGUAGE (default en, or auto), VIDEO_BRIEF_PYTHON, FFMPEG_PATH, FFPROBE_PATH.

A typical session

1. brief_probe /path/review.mov → 13:13, 2282×1316, audio

2. brief_transcribe → a minute later, the transcript

3. brief_scenes withFrames: true → where the screen changes, as images

4. For each item in the checklist: brief_slice from: "2:15" to: "4:10" → what she said and what she pointed at

5. brief_export outDir: docs/review-oct12 → the folder that goes into the repo next to the task

On an M1 Pro with the small model, one minute of speech transcribes in about 8 seconds on CPU.

Development

npm test          # vitest; ffmpeg and whisper are injected, no media needed
npm run typecheck

• src/media.ts — ffprobe / ffmpeg: probe, single-frame grabs (input seeking, fast on large files), scene detection

• src/transcripts.ts — background Whisper jobs, progress parsing, disk cache, slicing and search

• scripts/transcribe.py — Whisper runner that prints JSON and progress lines

• src/tools.ts — tool definitions and handlers

• src/index.ts — MCP wiring over stdio