mcp-video

Video editing and creation for AI agents.
Edit existing video with FFmpeg. Create new video from code with Remotion.
83 tools. 3 interfaces. Extensive automated and real-media test coverage.

Install • Quick Start • Tools • Remotion • Python • CLI • Templates • Agent Discovery • Contributing • Security • Support • Changelog • Roadmap

What is mcp-video?

mcp-video is an open-source video editing server built on the Model Context Protocol (MCP). It gives AI agents, developers, and video creators the ability to programmatically edit and create video files.

Two modes of operation:

1. Edit existing video with FFmpeg — trim, merge, overlay text, add audio, apply filters, stabilize, detect scenes, transcribe, and more. 83 tools covering the full editing pipeline.

2. Create new video from code with Remotion — scaffold React-based video compositions, preview them live, render to MP4, then post-process with mcp-video. 8 dedicated tools for programmatic video generation.

Think of it as FFmpeg + Remotion with an API that AI agents can actually use. Instead of memorizing cryptic flags, an agent calls structured tools with clear parameters and gets structured results back.

Three Ways to Use It

Table of Contents

• What is mcp-video?
• Installation
• Quick Start
• Agent Discovery
• MCP Tools
  • Core Video
  • AI-Powered
  • Remotion & Motion Graphics
  • Audio Synthesis
  • Visual Effects
  • Transitions
  • Layout & Motion Graphics
  • Quality & Guardrails
  • Image Analysis
• Remotion Integration
• Python Client
• CLI Reference
• Timeline DSL
• Templates
• Error Handling
• Architecture
• Testing
• Community & Support
• License

Installation

Prerequisites

FFmpeg must be installed:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

For Remotion features, you also need Node.js (18+) and npm.

Install

pip install mcp-video

Or run without installing:

uvx mcp-video

Check your local integration surface:

mcp-video doctor
mcp-video doctor --json

Quick Start

1. As an MCP Server (for AI agents)

Claude Code:

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

Claude Desktop — add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-video": {
      "command": "uvx",
      "args": ["mcp-video"]
    }
  }
}

Cursor — add to your .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-video": {
      "command": "uvx",
      "args": ["mcp-video"]
    }
  }
}

Then just ask your agent: "Trim this video from 0:30 to 1:00, add a title card, and resize for TikTok."

Agent Discovery

Machine-readable discovery files are published for agents and answer engines:

• llms.txt gives agents a compact project map with install snippets, entry points, and safety rules.
• docs/AI_AGENT_DISCOVERY.md gives richer positioning, query targets, integration snippets, and directory targets.
• robots.txt and sitemap.xml keep the GitHub Pages surface crawlable.

The canonical positioning is: an open source MCP server, Python client, and CLI for video editing and creation workflows, wrapping FFmpeg and Remotion for AI agents.

2. As a Python Library

from mcp_video import Client

editor = Client()

# Get video info
info = editor.info("interview.mp4")
print(f"Duration: {info.duration}s, Resolution: {info.resolution}")

# Trim, merge, add text, resize for TikTok
clip = editor.trim("interview.mp4", start="00:02:15", duration="00:00:30")
video = editor.merge(clips=["intro.mp4", clip.output_path, "outro.mp4"])
video = editor.add_text(video.output_path, text="EPISODE 42", position="top-center", size=48)
video = editor.add_audio(video.output_path, audio="music.mp3", volume=0.7, fade_in=2.0, fade_out=3.0)
result = editor.resize(video.output_path, aspect_ratio="9:16")

3. As a CLI Tool

mcp-video info video.mp4
mcp-video trim video.mp4 -s 00:02:15 -d 30
mcp-video convert video.mp4 -f webm -q high
mcp-video template tiktok video.mp4 --caption "Check this out!"

MCP Tools

83 tools across 9 categories. All return structured JSON with success, output_path, and operation metadata. On failure, they return {"success": false, "error": {...}} with auto-fix suggestions.

Core Video (40 tools)

AI-Powered (8 tools)

Remotion & Motion Graphics (8 tools)

Create videos programmatically using Remotion — a React framework for video. Scaffold projects, render compositions, then post-process with mcp-video.

Audio Synthesis (6 tools)

Generate audio from code — no external audio files needed. Pure NumPy, no extra dependencies.

Visual Effects (5 tools)

Transitions (3 tools)

Layout & Motion Graphics (7 tools)

Quality & Guardrails (3 tools)

Image Analysis (3 tools)

Remotion Integration

mcp-video includes 8 dedicated tools for Remotion — a React framework for creating videos programmatically. This lets AI agents create videos from scratch using React components, not just edit existing ones.

Typical Workflow

1. Create project    -> remotion_create_project
2. Scaffold composition -> remotion_scaffold_template (from a design spec)
3. Preview live       -> remotion_studio
4. Render             -> remotion_render
5. Post-process       -> remotion_to_mcpvideo (resize, add audio, normalize, etc.)

Example: Create a promotional video from code

from mcp_video import Client

editor = Client()

# 1. Scaffold a new Remotion project
project = editor.remotion_create_project("promo-video", template="hello-world")

# 2. Generate a composition from a design spec
spec = editor.remotion_scaffold_template(
    project_path=project.project_path,
    spec={
        "primary_color": "#CCFF00",
        "heading_font": "Inter",
        "target_fps": 30,
        "target_duration": 15,
    },
    slug="promo",
)

# 3. Render to video
render = editor.remotion_render(
    project_path=project.project_path,
    composition_id="promoComposition",
    codec="h264",
)

# 4. Or use the pipeline: render + post-process in one call
result = editor.remotion_to_mcpvideo(
    project_path=project.project_path,
    composition_id="promoComposition",
    post_process=[
        {"op": "resize", "params": {"aspect_ratio": "9:16"}},
        {"op": "normalize_audio", "params": {"target_lufs": -14}},
    ],
)

Requirements

• Node.js 18+ and npm
• No Python dependencies — Remotion runs via npx remotion as a subprocess
• Optional: install Remotion globally with npm i -g remotion for faster startup

Python Client

from mcp_video import Client

editor = Client()

Methods

Return Models

VideoInfo(path, duration, width, height, fps, codec, audio_codec, ...)
# .resolution  -> "1920x1080"
# .aspect_ratio -> "16:9"
# .size_mb -> 5.42

EditResult(success=True, output_path, duration, resolution, size_mb, format, operation)

ThumbnailResult(success=True, frame_path, timestamp)

StoryboardResult(success=True, frames=["f1.jpg", ...], grid="grid.jpg", count=8)

SceneDetectionResult(success=True, scenes=[(start, end), ...], scene_count=5)

ImageSequenceResult(success=True, frame_count=120, fps=30, duration=4.0, output_path)

SubtitleResult(success=True, subtitle_path, entries_count=15)

WaveformResult(success=True, peaks=[...], silence_regions=[...], bin_count=50)

QualityMetricsResult(success=True, psnr=45.2, ssim=0.98)

MetadataResult(success=True, metadata={...})

ColorExtractionResult(success=True, colors=[...], n_colors=5)

PaletteResult(success=True, harmony="complementary", colors=[...])

ProductAnalysisResult(success=True, colors=[...], description="...")

CLI Reference

mcp-video [command] [options]

Diagnostics:
  doctor              Check FFmpeg, Remotion, image, and AI dependencies

Core Editing:
  info                 Get video metadata
  trim                 Trim a video
  merge                Merge multiple clips
  add-text             Overlay text on a video
  add-audio            Add or replace audio track
  resize               Resize or change aspect ratio
  convert              Convert video format (with two-pass encoding)
  speed                Change playback speed
  thumbnail            Extract a single frame
  extract-frame        Extract a single frame (with --time flag)
  preview              Generate fast low-res preview
  storyboard           Extract key frames as storyboard
  subtitles            Burn subtitles into video
  generate-subtitles   Create SRT subtitles from text
  watermark            Add image watermark
  crop                 Crop to rectangular region
  rotate               Rotate and/or flip video
  fade                 Add video fade in/out
  export               Export with quality settings
  extract-audio        Extract audio track
  edit                 Execute timeline-based edit from JSON (file path or inline)
  filter               Apply visual filter (blur, sharpen, grayscale, ken_burns, etc.)
  blur                 Blur video
  color-grade          Apply color preset (warm, cool, vintage, etc.)
  normalize-audio      Normalize audio to LUFS target
  audio-waveform       Extract audio waveform data
  reverse              Reverse video playback
  chroma-key           Remove solid color background (green screen)
  stabilize            Stabilize shaky footage
  apply-mask           Apply image mask with feathering
  detect-scenes        Detect scene changes
  create-from-images   Create video from image sequence
  export-frames        Export video as image frames (--image-format for format)
  compare-quality      Compare PSNR/SSIM quality metrics
  read-metadata        Read video metadata tags
  write-metadata       Write video metadata tags
  batch                Apply operation to multiple files
  overlay-video        Picture-in-picture overlay
  split-screen         Place two videos side by side or top/bottom
  templates            List available video templates
  template             Apply a video template (tiktok, youtube-shorts, etc.)

Visual Effects:
  effect-vignette             Apply vignette (darkened edges)
  effect-glow                 Apply bloom/glow to highlights
  effect-noise                Apply film grain or digital noise
  effect-scanlines            Apply CRT-style scanlines overlay
  effect-chromatic-aberration Apply RGB channel separation

Transitions:
  transition-glitch     Glitch transition between two clips
  transition-morph      Mesh warp morph transition
  transition-pixelate   Pixel dissolve transition

AI Tools:
  video-ai-transcribe    Speech-to-text with Whisper
  video-ai-upscale      AI super-resolution upscaling
  video-ai-stem-separation  Separate audio stems with Demucs
  video-ai-scene-detect  Scene detection with perceptual hashing
  video-ai-color-grade   Auto color grading
  video-ai-remove-silence  Remove silent sections

Audio Synthesis:
  audio-synthesize      Generate audio from waveform synthesis
  audio-compose         Layer multiple audio tracks with mixing
  audio-preset          Generate preset sound effects
  audio-sequence        Compose timed audio event sequence
  audio-effects         Apply audio effects chain (reverb, lowpass, etc.)

Motion Graphics:
  video-text-animated   Add animated text (fade, slide-up, typewriter)
  video-mograph-count   Generate animated number counter
  video-mograph-progress  Generate progress bar / loading animation

Layout:
  video-layout-grid     Arrange multiple videos in a grid
  video-layout-pip      Picture-in-picture with border

Audio-Video:
  video-add-generated-audio  Add procedurally generated audio
  video-audio-spatial   3D spatial audio positioning

Quality & Analysis:
  video-auto-chapters    Auto-detect scene changes as chapters
  video-info-detailed    Extended metadata with scene detection
  video-quality-check    Visual quality checks (brightness, contrast, audio)
  video-design-quality-check  Design quality analysis
  video-fix-design-issues  Auto-fix design issues

Image Analysis:
  image-extract-colors  Extract dominant colors from an image
  image-generate-palette  Generate color harmony palette
  image-analyze-product  Analyze product image (colors + AI description)

Remotion Commands:
  remotion-render       Render a Remotion composition to video
  remotion-compositions List compositions in a Remotion project
  remotion-studio       Launch Remotion Studio for live preview
  remotion-still        Render a single frame as an image
  remotion-create       Scaffold a new Remotion project
  remotion-scaffold     Generate a composition from a design spec
  remotion-validate     Validate a Remotion project structure
  remotion-pipeline     Render + post-process in one step

Global Options:
  --format text|json   Output format (default: text — rich tables & spinners)
  --version            Show version and exit
  --mcp                Run as MCP server (default when no command given)

Timeline DSL

For complex multi-track edits, describe everything in a single JSON object:

editor.edit({
    "width": 1080,
    "height": 1920,
    "tracks": [
        {
            "type": "video",
            "clips": [
                {"source": "intro.mp4", "start": 0, "duration": 5},
                {"source": "main.mp4", "start": 5, "trim_start": 10, "duration": 30},
                {"source": "outro.mp4", "start": 35, "duration": 10},
            ],
            "transitions": [
                {"after_clip": 0, "type": "fade", "duration": 1.0},
                {"after_clip": 1, "type": "dissolve", "duration": 1.0},
            ],
        },
        {
            "type": "audio",
            "clips": [
                {"source": "music.mp3", "start": 0, "volume": 0.7, "fade_in": 2},
            ],
        },
        {
            "type": "text",
            "elements": [
                {"text": "EPISODE 42", "start": 0, "duration": 3, "position": "top-center",
                 "style": {"size": 48, "color": "white", "shadow": True}},
            ],
        },
        {
            "type": "image",
            "images": [
                {"source": "logo.png", "position": "top-right", "width": 200, "opacity": 0.8},
            ],
        },
    ],
    "export": {"format": "mp4", "quality": "high"},
})

Templates

Pre-built templates for common social media formats:

from mcp_video.templates import tiktok_template, youtube_video_template

# TikTok (9:16, 1080x1920)
timeline = tiktok_template(video_path="clip.mp4", caption="Check this out!", music_path="bgm.mp3")

# YouTube Shorts (9:16, title at top)
timeline = youtube_shorts_template("clip.mp4", title="My Short")

# Instagram Reel (9:16)
timeline = instagram_reel_template("clip.mp4", caption="Reel caption")

# YouTube Video (16:9, 1920x1080)
timeline = youtube_video_template(video_path="video.mp4", title="My Amazing Video",
                                   outro_path="subscribe.mp4", music_path="bgm.mp3")

# Instagram Post (1:1, 1080x1080)
timeline = instagram_post_template("clip.mp4", caption="Post caption")

# Execute any template
result = editor.edit(timeline)

Error Handling

mcp-video parses FFmpeg errors and returns structured, actionable responses:

{
  "success": false,
  "error": {
    "type": "encoding_error",
    "code": "unsupported_codec",
    "message": "Codec error: vp9 — Auto-convert input from vp9 to H.264/AAC before editing",
    "suggested_action": {
      "auto_fix": true,
      "description": "Auto-convert input from vp9 to H.264/AAC before editing"
    }
  }
}

Error Types

Architecture

mcp_video/
  __init__.py            # Exports Client
  __main__.py            # CLI entry point (argparse + Rich)
  client.py              # Python Client API (wraps all engines)
  server.py              # MCP server (83 tools + 4 resources)
  engine.py              # Core FFmpeg engine (40 video operations)
  models.py              # Pydantic models (VideoInfo, EditResult, Timeline DSL)
  errors.py              # Error hierarchy + FFmpeg stderr parser
  validation.py          # Shared validation constants / allowed values
  templates.py           # Social media templates (TikTok, YouTube, Instagram)
  audio_engine.py        # Procedural audio synthesis (pure NumPy)
  effects_engine.py      # Visual effects + motion graphics (FFmpeg filters)
  ffmpeg_helpers.py      # Shared FFmpeg utilities (v1.2.0)
  transitions_engine.py  # Clip transitions (glitch, pixelate, morph)
  ai_engine.py           # AI features (Whisper, Demucs, Real-ESRGAN, spatial audio)
  remotion_engine.py     # Remotion CLI wrapper (render, studio, scaffold, validate)
  remotion_models.py     # Remotion data models
  image_engine.py        # Image color analysis (K-means, palette generation)
  image_models.py        # Image data models
  quality_guardrails.py  # Automated quality checks (brightness, contrast, audio)
  design_quality.py      # Design quality + auto-fix (layout, typography, motion)
  limits.py              # Resource validation constants (max 4h, 8K, 4GB)

Dependencies:

• mcp>=1.0.0 — Model Context Protocol SDK
• pydantic>=2.0 — Data validation
• rich>=13.0 — Rich CLI output (tables, spinners, panels)
• ffmpeg — Video processing (external, required)
• node/npx — Remotion (external, optional)

Testing

mcp-video includes a broad automated test suite covering unit, integration, CLI, MCP server, security, and real-media workflows. The default CI path focuses on the non-slow Python test surface, while additional real-media and environment-sensitive tests can be run locally when the required tooling is available.

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (excluding slow/remotion)
pytest tests/ -v -m "not slow and not remotion"

# Run everything
pytest tests/ -v

# Run only unit tests (no FFmpeg needed)
pytest tests/test_models.py tests/test_errors.py tests/test_templates.py -v

Test Categories

Supported Formats

Video

Audio (extraction)

MP3, AAC, WAV, OGG, FLAC

Subtitles

SRT, WebVTT (burned into video)

Development

git clone https://github.com/pastorsimon1798/mcp-video.git
cd mcp-video

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

pytest tests/ -v -m "not slow and not remotion"

Community & Support

• Read CONTRIBUTING.md before opening a PR.
• Security reports: see SECURITY.md (private reporting path).
• Need help or want to request a feature? Start with SUPPORT.md.
• Expected behavior in community spaces: CODE_OF_CONDUCT.md.
• Discussions: ask questions, share demos, and float ideas in GitHub Discussions.
• Governance and maintainer expectations: GOVERNANCE.md and MAINTAINERS.md.
• Release history: CHANGELOG.md.

License

Apache 2.0 — see LICENSE.

Built on FFmpeg, Remotion, and the Model Context Protocol.

Important dependency licensing note

The Python package itself is released under Apache 2.0, but some optional tooling has its own terms:

• FFmpeg licensing depends on how FFmpeg is built and distributed.
• Remotion uses its own commercial/free license model and may require a paid company license depending on your organization and usage.

See LEGAL_REVIEW.md for a practical project-specific licensing and commercial-use summary.