video-edit-mcp
This server lets any MCP client edit video locally with ffmpeg — no cloud, no API keys.
Inspect media with
probe(container, duration, streams) andhealth(ffmpeg/ffprobe/Whisper availability).Cut & join:
trima single range,cutmultiple ranges in order,concatfiles with resolution/fps/audio normalization.Render with presets (
web-1080p,vertical-9x16,square,audio-only) or a multi-track timeline: transitions, still images with Ken Burns, overlay/HyperFrames layers, burned-in captions, loudness normalization.Captions:
transcribewith local Whisper (word timestamps),captions.generateto SRT/ASS/HyperFrames (plain, karaoke, pop, box),captions.renderto burn them in.Reframe to 9:16, 1:1, 16:9 or 4:5 via crop (with focus point or subject follow), color pad or blurred pad.
Audio:
audio.measure(LUFS/true peak/LRA),audio.loudnorm(two-pass),audio.mix(voice + music with sidechain ducking and fades, video stream-copied).Deliver a ZIP with
export.package: media,captions.srt,spec.jsonand checksums.Optionally render HyperFrames HTML compositions with
compose.
Provides video editing capabilities powered by local ffmpeg, exposing tools such as health checks (ffmpeg/ffprobe availability and versions) and probe (container, duration, and stream info of a local file), with a roadmap for cutting, concatenation, captions, reframing, audio mixing, and render presets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@video-edit-mcp check if ffmpeg is available and probe ~/Videos/interview.mp4"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
video-edit-mcp
Español · MIT
An open-source Model Context Protocol server that lets any assistant edit video locally with ffmpeg.
Cut, trim, join, reframe, caption, mix and render video from any MCP client (Claude Desktop, Cursor, …). Everything runs on your machine: ffmpeg for cut/mix/encode, optional HyperFrames for animated captions and composition, optional local Whisper for transcription. No cloud calls, no API keys.
Install
Requirements: Node 22+, ffmpeg and ffprobe on PATH.
Optional: @hyperframes/producer + headless Chrome (animated captions, compose, HTML layers; ffmpeg fallback otherwise), a Whisper CLI (whisper.cpp or faster-whisper/whisper-ctranslate2) for transcribe.
git clone https://github.com/Galvez92/video-edit-mcp.git
cd video-edit-mcp
npm ci && npm run build
node dist/index.js # stdio
node dist/index.js --http --port 3333 # Streamable HTTP at http://127.0.0.1:3333/mcpRelated MCP server: FFmpeg Python MCP Server
MCP client config
Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json or .cursor/mcp.json) use the same shape:
{
"mcpServers": {
"video-edit": {
"command": "node",
"args": ["/absolute/path/to/video-edit-mcp/dist/index.js"]
}
}
}All paths passed to tools are local file paths on the machine running the server.
Tools
Tool | What it does |
| ffmpeg / ffprobe / Whisper availability and versions |
| Container, duration, size and per-stream info of a media file |
| Keep one range; stream copy when keyframe-safe, re-encode otherwise |
| Keep several ranges of one file and join them in order |
| Join files into one, normalizing resolution / fps / audio |
| Encode a file or a multi-track timeline with a preset ( |
| Delivery ZIP: media, |
| Render a HyperFrames HTML composition to video (optional peer) |
| Local Whisper transcription with word timestamps |
| Transcript/SRT → SRT, ASS or animated HyperFrames captions ( |
| Burn captions into a video (HyperFrames or ffmpeg/libass), audio kept |
| Reframe to 9:16, 1:1, 16:9 or 4:5: crop (focus point or subject follow), color pad or blurred pad |
| Integrated loudness (LUFS), true peak and LRA |
| Two-pass loudness normalization (default −14 LUFS) |
| Voice + music with sidechain ducking and fades, video stream-copied |
End-to-end example
Ask your assistant, or call the tools directly:
probe { "path": "talk.mp4" }transcribe { "input": "talk.mp4", "wordTimestamps": true }→ segmentsrendera 9:16 cut with burned-in captions and normalized audio:
{ "preset": "vertical-9x16", "output": "out/final.mp4",
"timeline": { "width": 1080, "height": 1920, "fps": 30, "tracks": [
{ "id": "v", "kind": "video", "clips": [
{ "id": "a", "src": "talk.mp4", "in": 12, "out": 27 },
{ "id": "b", "src": "talk.mp4", "in": 40, "out": 52, "transition": { "type": "crossfade", "durationSec": 0.5 } } ] },
{ "id": "m", "kind": "audio", "clips": [
{ "id": "music", "src": "music.m4a", "in": 0, "out": 26.5, "gainDb": -14 } ] } ] },
"captions": { "transcript": "talk.transcript.json", "style": "box" },
"loudness": {} }export.package { "video": "out/final.mp4", "output": "out/final.zip", "preset": "vertical-9x16" }→ ZIP with the video,captions.srt,spec.jsonand checksums.
Timeline layer sizing
render layers keep their source aspect ratio: scale (fraction of frame width, or scaleMode: "native"), or width/height in px (one keeps aspect). When both width and height are given, fit defaults to contain (fit inside the box, centred); use cover to fill and crop, or fit: "stretch" explicitly to distort to the exact box. A layer with no size fills the frame. Off-frame positions are clamped and reported in warnings.
Captions in the final render
render accepts captions and burns them in after the timeline and layers are composed (times are program seconds):
{ "timeline": { ... }, "preset": "vertical-9x16", "output": "out/final.mp4",
"captions": { "srt": "subs.srt", "style": "box", "engine": "auto" } }Source (exactly one):
srt(path;.vttdetected),vtt(path),cues([{start,end,text}]), ortranscript(segments, thetranscribeoutput object, or a JSON path).style:plain|karaoke|pop|box;maxCharsPerLine/maxLineswrap transcripts.engine:auto(default: HyperFrames when the optional peer is installed, otherwise ffmpeg/libass with a warning),hyperframesorffmpeg. The burn-in pass encodes with the preset's video settings and copies the audio.The SRT actually burned is written next to the output (
final.srt, orsrtOutput) and reported incaptions.srt.export.packageincludes that sidecar ascaptions.srtwhensubtitlesis omitted (sidecarCaptions: falseto skip).
Still images on the timeline
A video-track clip whose src is a .png, .jpg/.jpeg or .webp is a still: pass durationSec (no in/out). It is framed to the preset (still.fit: contain, the default, pads; cover fills and crops), carries silent audio and joins neighbours with any transition.
{ "id": "title", "src": "poster.jpg", "durationSec": 3,
"still": { "fit": "cover", "kenBurns": { "zoomFrom": 1, "zoomTo": 1.25, "from": { "x": 0.3, "y": 0.5 }, "to": { "x": 0.6, "y": 0.4 } } } }Ken Burns is optional: zoom 1..4 and a focus point (0..1 of the frame) interpolated linearly over the clip. Stills are not allowed on audio tracks.
render also returns program: { durationSec, clipsSec, overlapSec, gapSec }: the effective program length is the sum of clips minus transition overlaps plus gaps (each transition shortens the program by its durationSec).
Loudness normalization
render and export.package accept loudness: { targetLufs?: -16, truePeakDb?: -1, lra?: 11 }. Off by default; pass {} for the defaults. Two-pass ffmpeg loudnorm on the final mix (after captions): pass 1 measures, pass 2 applies the measured values (linear gain when the true-peak ceiling allows it, otherwise limited: gain + 4x-oversampled limiter with up to 3 measured gain corrections, because loudnorm dynamic undershoots on short mixes). Video is stream-copied.
renderreturnsloudness: { target, before, after, mode }and writes<output>.loudness.json;export.packagecopies it intospec.jsonasloudnessNormalization(only while its checksum matches the file).export.package { loudness }normalizes a copy before packaging; the source file is untouched.spec.loudnessis always measured on the packaged file.
Roadmap
EDL / OTIO import
Published npm package
Development
npm test # ffmpeg tests skip if ffmpeg is missing
npm run lint && npm run typecheckSee AGENTS.md for conventions.
Third-party
HyperFrames (Apache-2.0) — optional peer dependency used as the composition/captions engine.
ffmpeg — invoked as an external binary.
¿Quieres generar video con IA? / Want AI video generation?
Prueba reelo-mcp: crea tableros, cotiza y genera videos con IA desde Claude, Cursor o tu cliente MCP, usando tus créditos de Reelo.
Try reelo-mcp: create boards, quote and generate AI videos from Claude, Cursor or any MCP client, using your Reelo credits.
Available Tools
15 toolsaudio.loudnormC
Two-pass loudness normalization of a media file to a target integrated loudness (default -14 LUFS) using ffmpeg loudnorm.
Inputs: input (required), output (required), truePeak, targetLufs.
audio.measureA
Measure integrated loudness (LUFS), true peak (dBTP) and loudness range (LRA) of a media file with ffmpeg loudnorm.
Inputs: input (required).
audio.mixA
Mix a video's voice track with background music, ducking the music under the voice with a sidechain compressor. Video is kept (stream copy); audio is re-encoded. Fades optional.
Inputs: music (required), video (required), output (required), duck, +3 more.
captions.generateB
Write captions from transcription segments or an SRT file: subtitle files (srt/ass) or a HyperFrames composition HTML for animated captions (karaoke word highlight, word-pop, background box).
Inputs: format (required), output (required), srt, style, +6 more.
captions.renderB
Burn captions onto a video and keep its audio. The HyperFrames engine (default) renders an animated caption layer; the ffmpeg engine burns in an ASS overlay and needs no extra dependency. Give it transcription segments, an SRT file, or a composition path (engine "hyperframes").
Inputs: input (required), output (required), fps, srt, +9 more.
composeA
Render a HyperFrames composition (HTML) to video. Needs the optional peer @hyperframes/producer and headless Chrome; returns an 'unavailable' error otherwise.
Inputs: output (required), composition (required), fps, format, +1 more.
concatA
Join several media files into one. Normalization scales/pads resolution, fps and audio to a common layout first.
Inputs: inputs (required), output (required), normalize, overwrite.
cutA
Keep the listed ranges of one file and join them in order, always re-encoded.
Inputs: input (required), output (required), segments (required), overwrite.
export.packageB
Build a delivery ZIP: the media file, optional captions.srt, spec.json (measured duration, resolution, fps, codecs, EBU R128 loudness, preset) and checksums.sha256.
Inputs: video (required), output (required), preset, loudness, +3 more.
healthA
Report whether ffmpeg/ffprobe and a local Whisper backend are available, with versions.
Inputs: no named parameters.
probeA
Inspect a local media file: container, duration, size and per-stream codec/resolution/fps/audio info.
Inputs: path (required).
reframeA
Reframe a video to 9:16, 1:1, 16:9 or 4:5. Modes: a centered crop (default), solid-color padding, or blurred-background padding. In "crop" mode, focusX/focusY bias the crop (0..1), and "follow" tracks the subject across time using an optional, lazily-loaded face detector.
Inputs: input (required), aspect (required), output (required), mode, +6 more.
renderA
Encode a file or assemble a timeline with a fixed delivery preset: web-1080p (16:9), vertical-9x16, square (H.264+AAC, fit-and-pad) or audio-only (AAC .m4a). Optional alpha overlay / HyperFrames layers on top (timed, stacked by zIndex, positioned and sized keeping their aspect; off-frame layers are clamped and reported in warnings). Optional captions (SRT/VTT/cues/transcript) burned in after composition with HyperFrames or the ffmpeg fallback. Timeline clips can be still images (png/jpg/webp, durationSec, contain/cover, Ken Burns). Optional two-pass loudness normalization of the final mix. Returns measured width/height/fps/codecs/bytes, the effective program duration (transition overlaps removed) and loudness before/after.
Inputs: output (required), preset (required), input, layers, +8 more.
transcribeA
Transcribe a local audio or video file with a local Whisper backend (whisper.cpp or faster-whisper): audio is extracted with ffmpeg to 16 kHz mono, and segments plus word-level timestamps are returned.
Inputs: input (required), model, language, wordTimestamps.
trimA
Cut one range out of a media file. Stream-copies when the range starts on a keyframe, re-encodes otherwise.
Inputs: end (required), input (required), start (required), output (required), +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target a clearly distinct operation (probe, trim, cut, concat, reframe, audio.*, captions.*). There is some overlap: render can burn captions and overlay HyperFrames layers, which partially duplicates captions.render, and compose vs render vs export.package touch adjacent rendering/assembly concerns, but descriptions provide enough guidance to choose correctly.
The set mixes bare verbs (render, transcribe, probe, trim, cut, concat, compose, reframe) with dotted namespace.action names (export.package, audio.measure, captions.generate). The namespacing is readable and groups related tools, but it is not a single consistent convention.
15 tools is well within the ideal range for a media-editing server and each tool covers a distinct pipeline stage (inspect, edit, reframe, caption, audio, compose, package, health). No tool appears redundant enough to be cut.
The surface covers the full edit lifecycle: probing, trimming/cutting/concatenating, reframing, captioning, loudness and mixing, composition, packaging, and environment health. Minor gaps exist, such as thumbnail/poster extraction, speed/scale adjustments, and explicit extract-audio, but these are workaroundable.
Maintenance
Related MCP Connectors
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Turn any video or audio link into files, transcripts and metadata, right from your AI agent.
AI video editor your agent can drive: plan scenes, edit a multi-track timeline, and render MP4s.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides powerful video and audio editing capabilities through FFmpeg, enabling AI assistants to perform professional-grade operations including format conversion, trimming, overlays, transitions, and advanced audio processing.2790MIT
- FlicenseBqualityDmaintenanceEnables AI assistants to perform video and audio processing tasks such as format conversion, cutting, merging, and adding effects via FFmpeg, with hardware acceleration support.193-
- AlicenseAqualityDmaintenanceEnables local media processing (video/audio) using FFmpeg and FFprobe, allowing frame extraction, audio conversion, and metadata retrieval through natural language.5MIT
- AlicenseBqualityCmaintenanceProvides Claude Code with local ffmpeg-based tools to probe, trim, concat, transform, overlay, mix audio, render JSON timelines, and run automated QA on video files—no API key required.9Apache 2.0