pastorsimon1798/mcp-video

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

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

pip install mcp-video

uvx mcp-video

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

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

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

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

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

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

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}},
    ],
)

from mcp_video import Client

editor = Client()

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="...")

mcp-video [command] [options]

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)

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"},
})

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)

{
  "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"
    }
  }
}

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 (82 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          # Centralized validation constants & helpers (v1.2.0)
  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)

# 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

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"