mcp-video

Video editing and creation for AI agents.
Edit existing video with FFmpeg. Create new video from code with Remotion.

Install • Quick Start • Tools • Full Reference • Agent Discovery • Contributing • Changelog

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:

1. Edit existing video with FFmpeg — trim, merge, overlay text, add audio, apply filters, stabilize, detect scenes, transcribe, and more.
2. Create new video from code with Remotion — scaffold React-based video compositions, preview live, render to MP4, then post-process.

Three interfaces:

Prerequisites: FFmpeg must be installed. For Remotion features, you also need Node.js 18+.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Install:

pip install mcp-video
# or run without installing:
uvx mcp-video

Verify your setup:

mcp-video doctor
mcp-video doctor --json

Claude Code:

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

Claude Desktop:

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

Cursor:

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

from mcp_video import Client

editor = Client()

info = editor.info("interview.mp4")
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)
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!"

83 tools across 9 categories. All return structured JSON. See the full tool reference for complete details.

Create videos programmatically with Remotion — a React framework for video.

1. Create project     -> remotion_create_project
2. Scaffold           -> remotion_scaffold_template
3. Preview live       -> remotion_studio
4. Render             -> remotion_render
5. Post-process       -> remotion_to_mcpvideo

See Remotion docs and the Python client reference.

from mcp_video import Client
editor = Client()

See the full Python client reference for all methods and return types.

mcp-video [command] [options]

See the full CLI reference for all commands and options.

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},
            ],
        },
        {
            "type": "audio",
            "clips": [
                {"source": "music.mp3", "start": 0, "volume": 0.7, "fade_in": 2},
            ],
        },
    ],
    "export": {"format": "mp4", "quality": "high"},
})

Pre-built templates for common social media formats:

from mcp_video.templates import tiktok_template, youtube_shorts_template

timeline = tiktok_template(video_path="clip.mp4", caption="Check this out!", music_path="bgm.mp3")
result = editor.edit(timeline)

Supports: TikTok, YouTube Shorts, Instagram Reels/Posts, YouTube Videos.

Structured, actionable errors with auto-fix suggestions:

{
  "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/
  client.py              # Python Client API
  server.py              # MCP server (83 tools + 4 resources)
  engine.py              # Core FFmpeg engine
  models.py              # Pydantic models
  errors.py              # Error hierarchy + FFmpeg stderr parser
  ffmpeg_helpers.py      # Shared FFmpeg utilities
  audio_engine.py        # Procedural audio synthesis
  effects_engine.py      # Visual effects + motion graphics
  transitions_engine.py  # Clip transitions
  ai_engine.py           # AI features (Whisper, Demucs, Real-ESRGAN)
  remotion_engine.py     # Remotion CLI wrapper
  image_engine.py        # Image color analysis
  quality_guardrails.py  # Automated quality checks

• llms.txt — compact project map for agents
• docs/AI_AGENT_DISCOVERY.md — richer positioning and integration snippets

git clone https://github.com/pastorsimon1798/mcp-video.git
cd mcp-video
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

• Contributing: CONTRIBUTING.md
• Security: SECURITY.md (private reporting path)
• Help: SUPPORT.md or GitHub Discussions
• Code of Conduct: CODE_OF_CONDUCT.md
• Changelog: CHANGELOG.md
• Roadmap: ROADMAP.md
• Governance: GOVERNANCE.md
• Maintainers: MAINTAINERS.md

Tests are excluded from the PyPI package. To run locally:

pip install -e ".[dev]"
pytest tests/ -v -m "not slow and not remotion"

See docs/TESTING.md for full test categories and CI details.

Apache 2.0 — see LICENSE.

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

See docs/LEGAL_REVIEW.md for dependency licensing notes.