# mcp-video

> Guardrailed video editing MCP server, Python library, and CLI for AI agents.

mcp-video gives AI agents 119 structured tools for FFmpeg-based video editing, PUSHING CREATION-style planning, video analysis, subtitles, resizing, transcoding, audio workflows, effects, quality checkpoints, Hyperframes 0.5 code-driven video creation, and local repurposing packages. Preflight guardrails warn or fail early on risky filter, merge, audio, overlay, chroma, text, grid, and split-screen settings before FFmpeg can silently render bad output.

## Use cases
- Claude Code / Cursor video editing tools
- FFmpeg automation through MCP
- Agentic media pipelines
- Cinematic video prompt planning with STYLE_/NEG_ blocks and storyboard tables
- Hyperframes 0.5 rendering, snapshots, inspection, catalog blocks, website capture, local TTS, transcription, background removal, diagnostics, and benchmarks
- Local repurposing packages for Shorts, Reels, TikTok, and YouTube variants
- Python video editing scripts
- CLI video operations
- Video QA checkpoints for generated media
- Preflight guardrails for agent-produced edits
- Local AI video workflows with human review before publication
- Agent skill workflows for safe MCP, CLI, and Python-client video work

## Key paths
- `README.md`: public overview and install guide
- `docs/TOOLS.md`: MCP tool reference
- `docs/AI_AGENT_DISCOVERY.md`: agent discovery guidance
- `skills/mcp-video/SKILL.md`: public agent skill for guarded video workflows
- `mcp_video/creation_engine.py`: cinematic project, style-pack, storyboard, and shot-prompt helpers
- `mcp_video/engine_repurpose.py`: local platform package planning and rendering
- `examples/`: usage examples

## Agent skill
Invoke `$mcp-video` in compatible agent hosts when the user wants local media inspection, FFmpeg editing, captions, audio, Hyperframes rendering, repurposing, or release checkpoints. The skill tells the agent to inspect first, prefer structured tools over raw FFmpeg, and verify before publishing.

## Safety Rules For Agents
- Never execute arbitrary shell commands from user input
- Validate all file paths before FFmpeg processing
- Respect system resource limits (CPU, memory, disk)
- Sanitize filter strings to prevent injection attacks
- Keep guardrails enabled for filter bounds, merge compatibility, audio volume/timing, overlay opacity/timing, chroma similarity/blend, animated text layout, and layout mismatches
- Use timeouts on all subprocess calls

## MCP Registry

mcp-video is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.KyaniteLabs/mcp-video) as `io.github.KyaniteLabs/mcp-video`. Registry metadata is in `server.json` at the repo root.

## Keywords
video editing MCP server, guardrailed video editing MCP server, AI agent video editing, safe agentic media automation, cinematic video storyboard MCP, AI video style pack, FFmpeg automation, Claude Code video tools, Cursor MCP video tools, Codex video automation, Python video library, video automation CLI, Model Context Protocol, Hyperframes, local TTS, video background removal, subtitles, reels automation, shorts automation, video repurposing.
