io.github.KyaniteLabs/mcp-video

See It Work

Tell the agent what you want in plain language:

"Trim this interview to the strongest 45 seconds, add burned captions, make it vertical, and quality-check it before export."

mcp-video turns that into typed, guardrailed tool calls — no FFmpeg flags to guess, no silently broken exports:

from mcp_video import Client
video = Client()

clip = video.trim("interview.mp4", start="00:02:15", duration="00:00:45")
video.ai_transcribe(clip.output_path, output_srt="captions.srt")
captioned = video.subtitles(clip.output_path, subtitle_file="captions.srt")
short = video.resize(captioned.output_path, aspect_ratio="9:16")
video.release_checkpoint(short.output_path)  # thumbnail + quality gate before you publish

Three things people use it for

• Repurposing — one recording into captioned Shorts, Reels, and TikTok packages with manifests and review artifacts.
• Podcast & interview cuts — find the strongest segment, normalize audio, add chapters, and export.
• Agent-driven media in CI — repeatable, reviewable edits from Claude Code, Cursor, Codex-style clients, or scripts.

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 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

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
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Run without a global install:

uvx --from mcp-video mcp-video doctor

Or install with pip:

pip install mcp-video
mcp-video doctor

Hyperframes 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.

Which extra do I need?

The core install covers all FFmpeg editing tools. Optional features ship as extras — install only what you use:

Mix freely, e.g. pip install "mcp-video[transcribe,image]". Run mcp-video doctor afterward — it reports exactly which features are available and what is missing.

En español

mcp-video es un servidor MCP de edición de video para agentes de IA: 119 herramientas estructuradas sobre FFmpeg para recortar, unir, subtitular, mezclar audio, aplicar efectos y reutilizar contenido (Shorts, Reels, TikTok), con barreras de seguridad que detectan parámetros riesgosos antes de renderizar.

Requisito: FFmpeg instalado y disponible en el PATH.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Instalación y diagnóstico
pip install mcp-video
mcp-video doctor

Para Claude Code:

claude mcp add mcp-video -- uvx --from mcp-video mcp-video

mcp-video doctor informa qué funciones están disponibles y qué falta instalar. La documentación completa está en inglés; los mensajes de error principales son bilingües.

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.py

The 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-video

Claude 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 tiktok

What Agents Can Do

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.

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() and Client.inspect().
• Unexpected keyword errors are converted into actionable MCPVideoError guidance.
• Do not publish agent-generated video without video_quality_check, video_release_checkpoint, and human visual/audio inspection.

Documentation

• Tool reference
• Python client reference
• CLI reference
• AI agent discovery guide
• FAQ
• llms.txt

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

• Contributing
• Code of Conduct
• Governance
• Maintainers
• Security
• Support
• Roadmap
• Changelog
• GitHub Discussions

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

If mcp-video is useful to you, star it — it helps other agent builders find it.

Built by Simon Gonzalez De Cruz — available for Forward-Deployed / Applied-AI engineering and contract work: simon@puenteworks.com.