<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"> <h1 align="center">mcp-video</h1> Video editing and creation for AI agents. Edit existing video with FFmpeg. Create new video from code with Remotion. 82 tools. 3 interfaces. 832 tests (707 fast, 116 slow/remotion). <a href="#installation">Install</a> • <a href="#quick-start">Quick Start</a> • <a href="#mcp-tools">Tools</a> • <a href="#remotion-integration">Remotion</a> • <a href="#python-client">Python</a> • <a href="#cli-reference">CLI</a> • <a href="#templates">Templates</a> • <a href="CONTRIBUTING.md">Contributing</a> • <a href="ROADMAP.md">Roadmap</a>

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:

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

| Interface | Best For | Example | |-----------|----------|---------| | MCP Server | AI agents (Claude Code, Cursor) | "Trim this video and add a title" | | Python Client | Scripts, automation, pipelines | editor.trim("v.mp4", start="0:30", duration="15") | | CLI | Shell scripts, quick ops, humans | mcp-video trim video.mp4 -s 0:30 -d 15 |

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

| Tool | Description | |------|-------------| | video_info | Get metadata: duration, resolution, codec, fps, file size | | video_info_detailed | Extended metadata with scene detection and dominant colors | | video_trim | Trim by start time + duration or end time | | video_merge | Concatenate clips with optional per-pair transitions | | video_add_text | Overlay text with positioning, font, color, shadow | | video_add_audio | Add, replace, or mix audio tracks with fade effects | | video_resize | Change resolution or apply preset aspect ratios (16:9, 9:16, 1:1, etc.) | | video_convert | Convert between mp4, webm, gif, mov (two-pass encoding) | | video_speed | Speed up or slow down (0.5x = slow-mo, 2x = time-lapse) | | video_reverse | Reverse video and audio playback | | video_fade | Fade in/out effects | | video_crop | Crop to rectangular region with offset | | video_rotate | Rotate 90/180/270 and flip horizontal/vertical | | video_filter | Apply filters: blur, sharpen, grayscale, sepia, invert, brightness, contrast, saturation, denoise, deinterlace, ken_burns | | video_blur | Blur with custom radius and strength | | video_color_grade | Color presets: warm, cool, vintage, cinematic, noir | | video_chroma_key | Remove solid color background (green screen) | | video_stabilize | Stabilize shaky footage (requires FFmpeg with vidstab) | | video_subtitles | Burn SRT/VTT subtitles into video | | video_generate_subtitles | Create SRT from text entries, optionally burn in | | video_watermark | Add image watermark with opacity and positioning | | video_overlay | Picture-in-picture overlay | | video_split_screen | Side-by-side or top/bottom layout | | video_edit | Full timeline-based edit from JSON DSL | | video_detect_scenes | Auto-detect scene changes with threshold control | | video_create_from_images | Create video from image sequence | | video_export_frames | Export video as individual image frames | | video_extract_audio | Extract audio as mp3, wav, aac, ogg, or flac | | video_extract_frame | Extract a single frame at any timestamp | | video_thumbnail | Extract a frame (auto-selects 10% into video) | | video_preview | Generate fast low-res preview | | video_storyboard | Extract key frames as a grid for review | | video_compare_quality | Compare PSNR/SSIM quality metrics between videos | | video_read_metadata | Read video metadata tags | | video_write_metadata | Write video metadata tags | | video_apply_mask | Apply image mask with edge feathering | | video_normalize_audio | Normalize loudness to LUFS target (-16 YouTube, -23 broadcast, -14 Spotify) | | video_audio_waveform | Extract audio waveform peaks and silence regions | | video_batch | Apply same operation to multiple files | | video_export | Render final video with quality presets |

AI-Powered (7 tools)

| Tool | Description | Dependencies | |------|-------------|--------------| | video_ai_remove_silence | Auto-remove silent sections with configurable threshold | FFmpeg | | video_ai_transcribe | Speech-to-text with timestamp alignment | openai-whisper | | video_ai_scene_detect | ML-enhanced scene change detection (perceptual hashing) | imagehash, Pillow | | video_ai_stem_separation | Isolate vocals, drums, bass, other instruments | demucs | | video_ai_upscale | AI super-resolution upscaling (2x or 4x) | realesrgan or opencv-python | | video_ai_color_grade | Auto color grading with style presets or reference matching | FFmpeg | | video_audio_spatial | 3D 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.

| Tool | Description | |------|-------------| | remotion_create_project | Scaffold a new Remotion project (blank or hello-world template) | | remotion_scaffold_template | Generate a composition from a desi

MCP Video

Install / Use

README