mcp-video
Provides structured MCP tools that wrap FFmpeg for video editing workflows, including trimming, merging, resizing, cropping, rotating, transcoding, adding subtitles/overlays/effects, processing audio, and analyzing or validating media output.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Public Discovery
mcp-video is a free, open-source Model Context Protocol (MCP) server, Python library, and CLI that gives AI agents a real video-editing surface. It wraps FFmpeg, PUSHING CREATION-style planning, media analysis, quality checks, subtitles, audio generation, effects, Hyperframes 0.5 rendering, local repurposing packages, and guardrails for risky edit parameters behind structured tool schemas.
Best-fit searches:
video editing MCP server
AI agent video editing
FFmpeg MCP tools
Claude Code video editing
Cursor MCP video tools
Python video editing library
subtitle automation
reels and shorts automation
agentic media pipeline
local AI video workflow
Hyperframes video creation
YouTube Shorts repurposing
Related MCP server: free-video-edit-mcp
Why It Exists
AI agents can write FFmpeg commands, but they should not have to guess flags, parse brittle stderr, or silently publish broken media. mcp-video gives agents typed operations, inspectable tool metadata, structured results, preflight guardrails, and quality checkpoints so a video workflow can be automated and reviewed without turning into shell-command roulette.
Use it when you want an AI assistant to:
trim, merge, resize, crop, rotate, transcode, or export video;
add text, subtitles, watermarks, overlays, filters, fades, effects, and transitions;
extract audio, normalize audio, synthesize audio, add generated audio, or create waveforms;
detect scenes, make thumbnails, generate storyboards, compare quality, and create release checkpoints;
scaffold cinematic projects, read STYLE_/NEG_ blocks, parse storyboard tables, and expand shot prompts;
create new Hyperframes projects, inspect rendered layouts, capture websites, generate local speech, remove backgrounds, and post-process the result with FFmpeg tools;
repurpose one source video into vertical, horizontal, and square local delivery packages with manifests and review artifacts;
drive repeatable media workflows from Claude Code, Cursor, Codex-style clients, scripts, or CI.
Installation
Prerequisite: FFmpeg must be installed and available on PATH.
# macOS
<div align="center">
<img src="capa/logo.svg" alt="Arckhé AI" height="48" />
<p><strong>Arckhé AI</strong></p>
</div>
brew install ffmpeg
# Ubuntu/Debian
sudo apt install ffmpegRun without a global install:
uvx --from mcp-video mcp-video doctorOr install with pip:
pip install mcp-video
mcp-video doctorHyperframes tools additionally need Node.js 22+ and a resolvable Hyperframes CLI. Install/pin Hyperframes in the active Node package layout, add hyperframes to PATH, or set MCP_VIDEO_HYPERFRAMES_COMMAND.
Quick Start
Try the receipt-backed proof first
From a clone of this repo, run the smallest confidence workflow before wiring an agent host:
uv run --no-project --with mcp-video python workflows/05-confidence-baseline/workflow.py
uv run --no-project --with mcp-video python workflows/benchmarks/run_confidence_benchmark.pyThe workflow generates a tiny source clip, creates a checked vertical video, runs quality/release checkpoint steps, and writes workflows/05-confidence-baseline/output/video_receipt.json.
Proof notes live in docs/proofs/.
Claude Code
claude mcp add mcp-video -- uvx --from mcp-video mcp-videoClaude Desktop
{
"mcpServers": {
"mcp-video": {
"command": "uvx",
"args": ["--from", "mcp-video", "mcp-video"]
}
}
}Cursor
{
"mcpServers": {
"mcp-video": {
"command": "uvx",
"args": ["--from", "mcp-video", "mcp-video"]
}
}
}Then ask your agent:
Trim this interview into a 45-second vertical clip, add burned captions, normalize the audio, make a thumbnail, and create a release checkpoint before export.
Agent Skill
mcp-video includes a public agent skill at skills/mcp-video/SKILL.md. Use $mcp-video in compatible agent hosts when you want the agent to choose between the MCP server, CLI, and Python client while preserving the inspect, edit, verify, and human-review workflow.
Python Client
from mcp_video import Client
editor = Client()
clip = editor.trim("interview.mp4", start="00:02:15", duration="00:00:45")
caption_file = "captions.srt"
editor.ai_transcribe(clip.output_path, output_srt=caption_file)
captioned = editor.subtitles(clip.output_path, subtitle_file=caption_file)
vertical = editor.resize(captioned.output_path, aspect_ratio="9:16")
checkpoint = editor.release_checkpoint(vertical.output_path)
print(checkpoint["thumbnail"])
print(checkpoint["storyboard"])CLI
mcp-video info interview.mp4
mcp-video trim interview.mp4 -s 00:02:15 -d 45
mcp-video video-ai-transcribe clip.mp4 --output captions.srt
mcp-video subtitles clip.mp4 captions.srt
mcp-video resize clip.mp4 --aspect-ratio 9:16
mcp-video video-quality-check clip.mp4
mcp-video repurpose clip.mp4 --platforms youtube-shorts instagram-reel tiktokWhat Agents Can Do
Workflow | Example prompt |
Social clips | "Turn this landscape recording into a captioned TikTok and YouTube Short." |
Podcast production | "Find the strongest segment, trim it, normalize audio, add chapters, and export." |
Product demos | "Create a short launch video from screenshots, title cards, and voiceover." |
Cinematic planning | "Create a style pack and storyboard, then render shot prompts for generation." |
Quality review | "Compare these two exports, make thumbnails, and flag visual or audio problems." |
Batch automation | "Convert this folder of clips to web-ready MP4 with consistent loudness." |
Code-created video | "Scaffold a Hyperframes composition, inspect it, render it, then add subtitles and a watermark." |
Local repurposing | "Turn this master clip into Shorts, Reels, TikTok, and YouTube assets with thumbnails and a manifest." |
MCP Tools
mcp-video currently registers 119 MCP tools. The table below summarizes the documented core categories; search_tools lets agents discover the exact operation they need without loading every tool description into context.
Category | Count | Highlights |
Core video editing | 32 | trim, merge, resize, crop, rotate, convert, overlays, subtitles, export, cleanup, templates, merge-compatibility guardrails |
Cinematic creation | 4 | project scaffold, style-pack parsing, storyboard parsing, shot prompt expansion |
AI-assisted media | 11 | transcription, scene detection, upscaling, stem separation, silence removal, color grading |
Hyperframes | 18 | init, preview, render, snapshots, inspect, catalog, website capture, local TTS, transcription, background removal, diagnostics, benchmark, post-process |
Repurposing | 2 | dry-run manifests, platform-ready variants, thumbnails, storyboards, release checkpoints |
Procedural audio | 7 | synthesize, compose, presets, effects, sequences, generated audio, spatial audio, mix-parameter guardrails |
Visual effects | 8 | vignette, glow, noise, scanlines, chromatic aberration, luma key, mask, shape mask, bounded filter parameters |
Transitions | 3 | glitch, morph, pixelate |
Layout and motion | 6 | grid, picture-in-picture, split-screen, animated text, counters, progress bars, auto-chapters, layout mismatch warnings |
Analysis | 8 | scene detection, thumbnail, preview, storyboard, quality compare, metadata, waveform, release checkpoint |
Image analysis | 3 | extract colors, generate palettes, analyze product images |
Discovery | 1 |
|
from mcp_video import Client
editor = Client()
matches = editor.search_tools("subtitle")
print(matches["tools"])Full reference: docs/TOOLS.md
Agent-Safe Workflow
For autonomous agents, the intended path is inspect, edit, verify, then ask a human to review release artifacts:
from mcp_video import Client
client = Client()
print(client.inspect("trim"))
result = client.pipeline(
[
{"op": "trim", "input": "source.mp4", "start": "00:01:00", "duration": "00:00:45"},
{"op": "add_text", "text": "Launch clip", "position": "top-center"},
{"op": "normalize_audio"},
{"op": "resize", "aspect_ratio": "9:16"},
{"op": "export", "quality": "high"},
{"op": "release_checkpoint"},
],
output_path="final-short.mp4",
)Safety contract:
Media-producing calls return structured results with output paths.
High-risk edit paths now run preflight guardrails before FFmpeg execution: filter bounds, merge compatibility, audio mix volume/timing, overlay/watermark/chroma opacity and similarity, animated text timing/overflow, and grid/split-screen mismatch warnings.
Analysis and discovery calls return structured JSON reports.
Tool discovery is available through
search_tools()andClient.inspect().Unexpected keyword errors are converted into actionable
MCPVideoErrorguidance.Do not publish agent-generated video without
video_quality_check,video_release_checkpoint, and human visual/audio inspection.
Documentation
Testing
Development verification lives in docs/TESTING.md. Keep public-surface, media workflow, and security checks current when changing tool behavior.
Development
git clone https://github.com/KyaniteLabs/mcp-video.git
cd mcp-video
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v -m "not slow and not hyperframes"Community
License
Apache 2.0. See LICENSE.
Built with FFmpeg, Hyperframes, and the Model Context Protocol.
Part of KyaniteLabs
More from KyaniteLabs. Related projects:
Epoch — time-estimation MCP server (PERT) for AI agents
DialectOS — Spanish dialect localization MCP server & CLI
checkyourself — local-first production-readiness checks for AI-built code
→ More at kyanitelabs.tech
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
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.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
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
- AlicenseBqualityCmaintenanceEnables AI agents to programmatically edit videos via FFmpeg, providing tools for probing, trimming, concatenating, timeline composition, LUT generation/application, rendering, and edit verification over MCP.162MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to edit video locally through FFmpeg: probing media, validating and previewing JSON edit projects, rendering short-form clips with captions, reframing, transitions and ducked music. Also analyses existing videos and applies or saves reusable format templates, without cloud services or API keys.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceGives coding agents a local FFmpeg video-editing engine exposed over MCP, enabling them to probe, cut, join, reframe, caption, normalize audio, and verify the resulting media without cloud services or API keys. Every operation returns structured JSON and self-checks its own output against delivery specs.16,037 npmMIT