Newcontext-mode—Save 98% of your AI coding agent's context windowLearn more
MCP Directory
ServersClientsBlog

context-mode

Save 98% of your AI coding agent's context window. Works with Claude Code, Cursor, Copilot, Codex, and more.

Try context-mode
MCP Directory

Model Context Protocol Directory

MKSF LTD
Suite 8805 5 Brayford Square
London, E1 0SG

MCP Directory

  • About
  • Blog
  • Documentation
  • Contact

Menu

  • Servers
  • Clients

© 2026 model-context-protocol.com

The Model Context Protocol (MCP) is an open standard for AI model communication.
Powered by Mert KoseogluSoftware Forge
  1. Home
  2. Clients
  3. mcp-video

mcp-video

GitHub
Website

Video editing MCP server for AI agents. 82 tools, 690+ tests, 3 interfaces. Works with Claude Code, Cursor, and any MCP client. Local, fast, free.

5
3
<p align="center"> <img src="https://img.shields.io/badge/version-1.2.0-blue.svg" alt="Version"> <img src="https://img.shields.io/badge/tests-832-brightgreen.svg" alt="Tests"> <a href="https://github.com/pastorsimon1798/mcp-video/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/pastorsimon1798/mcp-video/.github/workflows/ci.yml?branch=master&label=CI" alt="CI"></a> <img src="https://img.shields.io/badge/tools-82%20MCP%20tools-orange.svg" alt="Tools"> <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"> <img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python"> </p> <h1 align="center">mcp-video</h1> <p align="center"> <strong>Video editing and creation for AI agents.</strong><br> Edit existing video with FFmpeg. Create new video from code with Remotion.<br> 82 tools. 3 interfaces. 832 tests (707 fast, 116 slow/remotion). </p> <p align="center"> <a href="#installation">Install</a> &bull; <a href="#quick-start">Quick Start</a> &bull; <a href="#mcp-tools">Tools</a> &bull; <a href="#remotion-integration">Remotion</a> &bull; <a href="#python-client">Python</a> &bull; <a href="#cli-reference">CLI</a> &bull; <a href="#templates">Templates</a> &bull; <a href="CONTRIBUTING.md">Contributing</a> &bull; <a href="ROADMAP.md">Roadmap</a> </p>

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

InterfaceBest ForExample
MCP ServerAI agents (Claude Code, Cursor)"Trim this video and add a title"
Python ClientScripts, automation, pipelineseditor.trim("v.mp4", start="0:30", duration="15")
CLIShell scripts, quick ops, humansmcp-video trim video.mp4 -s 0:30 -d 15

Table of Contents

  • What is mcp-video?
  • Installation
  • Quick Start
  • 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
  • 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

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

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

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

ToolDescription
video_infoGet metadata: duration, resolution, codec, fps, file size
video_info_detailedExtended metadata with scene detection and dominant colors
video_trimTrim by start time + duration or end time
video_mergeConcatenate clips with optional per-pair transitions
video_add_textOverlay text with positioning, font, color, shadow
video_add_audioAdd, replace, or mix audio tracks with fade effects
video_resizeChange resolution or apply preset aspect ratios (16:9, 9:16, 1:1, etc.)
video_convertConvert between mp4, webm, gif, mov (two-pass encoding)
video_speedSpeed up or slow down (0.5x = slow-mo, 2x = time-lapse)
video_reverseReverse video and audio playback
video_fadeFade in/out effects
video_cropCrop to rectangular region with offset
video_rotateRotate 90/180/270 and flip horizontal/vertical
video_filterApply filters: blur, sharpen, grayscale, sepia, invert, brightness, contrast, saturation, denoise, deinterlace, ken_burns
video_blurBlur with custom radius and strength
video_color_gradeColor presets: warm, cool, vintage, cinematic, noir
video_chroma_keyRemove solid color background (green screen)
video_stabilizeStabilize shaky footage (requires FFmpeg with vidstab)
video_subtitlesBurn SRT/VTT subtitles into video
video_generate_subtitlesCreate SRT from text entries, optionally burn in
video_watermarkAdd image watermark with opacity and positioning
video_overlayPicture-in-picture overlay
video_split_screenSide-by-side or top/bottom layout
video_editFull timeline-based edit from JSON DSL
video_detect_scenesAuto-detect scene changes with threshold control
video_create_from_imagesCreate video from image sequence
video_export_framesExport video as individual image frames
video_extract_audioExtract audio as mp3, wav, aac, ogg, or flac
video_extract_frameExtract a single frame at any timestamp
video_thumbnailExtract a frame (auto-selects 10% into video)
video_previewGenerate fast low-res preview
video_storyboardExtract key frames as a grid for review
video_compare_qualityCompare PSNR/SSIM quality metrics between videos
video_read_metadataRead video metadata tags
video_write_metadataWrite video metadata tags
video_apply_maskApply image mask with edge feathering
video_normalize_audioNormalize loudness to LUFS target (-16 YouTube, -23 broadcast, -14 Spotify)
video_audio_waveformExtract audio waveform peaks and silence regions
video_batchApply same operation to multiple files
video_exportRender final video with quality presets

AI-Powered (7 tools)

ToolDescriptionDependencies
video_ai_remove_silenceAuto-remove silent sections with configurable thresholdFFmpeg
video_ai_transcribeSpeech-to-text with timestamp alignmentopenai-whisper
video_ai_scene_detectML-enhanced scene change detection (perceptual hashing)imagehash, Pillow
video_ai_stem_separationIsolate vocals, drums, bass, other instrumentsdemucs
video_ai_upscaleAI super-resolution upscaling (2x or 4x)realesrgan or opencv-contrib-python
video_ai_color_gradeAuto color grading with style presets or reference matchingFFmpeg
video_audio_spatial3D spatial audio positioning (azimuth + elevation)FFmpeg

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.

ToolDescription
remotion_create_projectScaffold a new Remotion project (blank or hello-world template)
remotion_scaffold_templateGenerate a composition from a design spec (colors, fonts, FPS, duration)
remotion_renderRender a Remotion composition to video (MP4)
remotion_stillRender a single frame as an image (PNG/JPEG/WebP)
remotion_compositionsList all compositions in a project
remotion_studioLaunch Remotion Studio for live preview
remotion_validateCheck project structure and dependencies
remotion_to_mcpvideoPipeline: render with Remotion, then post-process with mcp-video (resize, convert, add audio, normalize, add text, fade, watermark)

Audio Synthesis (6 tools)

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

ToolDescription
audio_synthesizeGenerate waveforms: sine, square, sawtooth, triangle, noise. With envelopes, reverb, filtering.
audio_preset15 pre-configured sounds: UI blips, ambient drones, notification chimes, data sounds
audio_sequenceCompose timed audio events into a layered track
audio_composeMix multiple WAV tracks with individual volume control
audio_effectsApply effects chain: lowpass, reverb, normalize, fade
video_add_generated_audioGenerate audio and add it to a video in one call

Visual Effects (5 tools)

ToolDescription
effect_vignetteDarken edges for cinematic focus
effect_chromatic_aberrationRGB color separation (glitch aesthetic)
effect_scanlinesRetro CRT scanline effect with flicker
effect_noiseFilm grain and digital noise
effect_glowBloom/glow for highlights

Transitions (3 tools)

ToolDescription
transition_glitchRGB shift + noise for digital distortion
transition_pixelateBlock dissolve with configurable pixel size
transition_morphMesh warp transition

Layout & Motion Graphics (7 tools)

ToolDescription
video_layout_gridGrid layout for multiple videos (2x2, 3x1, etc.)
video_layout_pipPicture-in-picture with border and positioning
video_text_animatedAnimated text overlays (fade, slide, typewriter)
video_text_subtitlesBurn subtitles with custom styling
video_mograph_countAnimated number counter video
video_mograph_progressProgress bar/circle/dots animation
video_auto_chaptersAuto-detect scenes and create chapter timestamps

Quality & Guardrails (3 tools)

ToolDescription
video_quality_checkCheck brightness, contrast, saturation, audio levels, color balance. Returns scores.
video_design_quality_checkFull design quality analysis: layout, typography, color, motion, composition
video_fix_design_issuesAuto-fix brightness, contrast, saturation, and audio level issues

Image Analysis (3 tools)

ToolDescription
image_extract_colorsExtract dominant colors via K-means clustering (1-20 colors)
image_generate_paletteGenerate color harmony palette (complementary, analogous, triadic, split-complementary)
image_analyze_productExtract colors + optional AI product description (Claude Vision)

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

MethodReturnsDescription
info(path)VideoInfoVideo metadata (duration, resolution, codec, fps, size)
trim(input, start, duration?, end?, output?)EditResultTrim by start time + duration or end time
merge(clips, output?, transitions?, transition_duration?)EditResultConcatenate clips with per-pair transitions
add_text(video, text, position?, font?, size?, color?, shadow?, start_time?, duration?, output?)EditResultOverlay text on video
add_audio(video, audio, volume?, fade_in?, fade_out?, mix?, start_time?, output?)EditResultAdd or replace audio track
resize(video, width?, height?, aspect_ratio?, quality?, output?)EditResultResize or change aspect ratio
convert(video, format?, quality?, output?)EditResultConvert format (mp4/webm/gif/mov)
speed(video, factor?, output?)EditResultChange playback speed
thumbnail(video, timestamp?, output?)ThumbnailResultExtract single frame
preview(video, output?, scale_factor?)EditResultFast low-res preview
storyboard(video, output_dir?, frame_count?)StoryboardResultKey frames + grid
subtitles(video, subtitle_file, output?)EditResultBurn subtitles into video
watermark(video, image, position?, opacity?, margin?, output?)EditResultAdd image watermark
crop(video, width, height, x?, y?, output?)EditResultCrop to rectangular region
rotate(video, angle?, flip_horizontal?, flip_vertical?, output?)EditResultRotate and/or flip video
fade(video, fade_in?, fade_out?, output?)EditResultVideo fade in/out effect
export(video, output?, quality?, format?)EditResultRender with quality settings
edit(timeline, output?)EditResultExecute full timeline edit from JSON
extract_audio(video, output?, format?)EditResultExtract audio as file path
filter(video, filter_type, params?, output?)EditResultApply visual filter
blur(video, radius?, strength?, output?)EditResultBlur video
color_grade(video, preset?, output?)EditResultApply color preset
normalize_audio(video, target_lufs?, output?)EditResultNormalize audio to LUFS target
overlay_video(background, overlay, position?, width?, opacity?, start_time?, duration?, output?)EditResultPicture-in-picture overlay
split_screen(left, right, layout?, output?)EditResultSide-by-side or top/bottom layout
reverse(video, output?)EditResultReverse video and audio playback
chroma_key(video, color?, similarity?, blend?, output?)EditResultRemove solid color background
stabilize(video, smoothing?, zoom?, output?)EditResultStabilize shaky footage
apply_mask(video, mask, feather?, output?)EditResultApply image mask with feathering
detect_scenes(video, threshold?, output?)SceneDetectionResultAuto-detect scene changes
create_from_images(images, fps?, output?)ImageSequenceResultCreate video from images
export_frames(video, fps?, output_dir?)ImageSequenceResultExport video as frames
compare_quality(video, reference, output?)QualityMetricsResultCompare PSNR/SSIM metrics
read_metadata(video)MetadataResultRead video metadata tags
write_metadata(video, metadata, output?)EditResultWrite video metadata tags
generate_subtitles(entries, output?, burn?)SubtitleResultCreate SRT subtitles
audio_waveform(video, bins?)WaveformResultExtract audio waveform
batch(inputs, operation, params?)dictApply operation to multiple files
extract_colors(image_path, n_colors?)ColorExtractionResultExtract dominant colors
generate_palette(image_path, harmony?, n_colors?)PaletteResultGenerate color harmony palette
analyze_product(image_path, use_ai?, n_colors?)ProductAnalysisResultExtract colors + optional AI description

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]

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

ErrorTypeAuto-FixDescription
FFmpegNotFoundErrordependency_errorNoFFmpeg not installed
FFprobeNotFoundErrordependency_errorNoFFprobe not installed
InputFileErrorinput_errorNoFile doesn't exist or invalid
CodecErrorencoding_errorYesUnsupported codec
ResolutionMismatchErrorencoding_errorYesClips have different resolutions
ProcessingErrorprocessing_errorNoFFmpeg processing failed
ExportErrorexport_errorNoExport/rendering failed
ResourceErrorresource_errorNoInsufficient disk space or memory
MCPVideoErrorvalidation_errorNoInvalid parameter (v1.2.0+)

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

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

832 tests across 22 test files. 707 run by default (fast unit + integration tests). 116 marked @slow (real media) or @remotion (Node.js) — run with pytest tests/ -v. Includes an adversarial security audit.

# 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

CategoryFilesWhat It Tests
Unittest_models, test_errors, test_templatesPure Python, no FFmpeg
Core Enginetest_engine, test_engine_advanced, test_client, test_serverFFmpeg operations, API wrapper
CLItest_cliAll CLI commands via subprocess
Remotiontest_remotion_engineRemotion CLI wrapper (mocked)
AI Featurestest_ai_featuresAI tools (mocked where needed)
Effectstest_transitions, test_audio_presetsTransitions and audio presets
Qualitytest_quality_guardrailsQuality scoring
Imagetest_image_engineColor extraction, palettes
Securitytest_adversarial_audit, test_red_teamFFmpeg injection, path validation, parameter bounds
Real Mediatest_real_media, test_real_all_features, test_real_exhaustiveReal FFmpeg operations (marked @slow)
E2Etest_e2eMulti-step workflows

Supported Formats

Video

FormatContainerVideo CodecAudio Codec
MP4mp4H.264 (libx264)AAC
WebMwebmVP9 (libvpx-vp9)Opus
MOVmovH.264 (libx264)PCM
GIFgifPalette-basedNone

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"

License

Apache 2.0 — see LICENSE.

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

Repository

PA
Pastorsimon1798

Pastorsimon1798/mcp-video

Created

March 21, 2026

Updated

April 13, 2026

Language

Python

Category

AI