mcp-video

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

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

What is mcp-video?

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 Hyperframes (HTML-native, Apache 2.0) — scaffold compositions, preview live, render to MP4, then post-process.

Three interfaces:

Installation

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

# 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

Quick Start

As an MCP Server (for AI agents)

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

As a Python Library

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

Agent-safe Python workflow

For autonomous agents, prefer inspection, pipeline chaining, and a release checkpoint:

from mcp_video import Client

client = Client()
print(client.inspect("create_from_images"))  # Real params, aliases, return type

result = client.pipeline(
    [
        {"op": "create_from_images", "images": frames, "fps": 30},
        {"op": "effect_glow", "intensity": 0.2},  # safe capped default
        {"op": "add_audio", "audio_path": "soundtrack.wav", "mix": True},
        {"op": "export", "quality": "high"},
    ],
    output_path="final.mp4",
)

checkpoint = client.release_checkpoint(result.output_path)
print(checkpoint["thumbnail"], checkpoint["storyboard"])

Agent contract:

• Media-producing client calls return EditResult with .output_path.
• Analysis/discovery calls return typed reports or dictionaries.
• Client.inspect(name) exposes parameters, aliases, category, and return type.
• Raw unexpected-keyword errors are converted into actionable MCPVideoError guidance.
• Do not publish agent-generated video without assert_quality() or release_checkpoint() plus human visual/audio inspection.

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

85 unique MCP tools across 10 categories, plus a search_tools meta-tool for fast discovery. All return structured JSON. See the full tool reference for complete details.

Tool discovery:

from mcp_video import Client
editor = Client()
results = editor.search_tools("subtitle")  # Find subtitle-related tools

Hyperframes Integration

Create videos programmatically with Hyperframes — an HTML-native framework for video (Apache 2.0).

1. Create project     -> hyperframes_init
2. Add blocks         -> hyperframes_add_block
3. Preview live       -> hyperframes_preview
4. Render             -> hyperframes_render
5. Post-process       -> hyperframes_to_mcpvideo

See Hyperframes docs and the Python client reference.

Hyperframes Integration

Create videos programmatically with Hyperframes — an HTML-native framework for video.

1. Init project       -> hyperframes_init
2. Add blocks         -> hyperframes_add_block
3. Preview live       -> hyperframes_preview
4. Render             -> hyperframes_render
5. Post-process       -> hyperframes_to_mcpvideo

See Hyperframes docs and the Python client reference.

Python Client

from mcp_video import Client
editor = Client()

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

CLI Reference

mcp-video [command] [options]

See the full CLI reference for all commands and options.

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

Templates

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.

Error Handling

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

Workflows

ICM-style staged pipelines for common productions — with CONTEXT.md stage contracts, references/ factory config, and runnable workflow.py scripts.

cd workflows/01-social-media-clip
python workflow.py /path/to/video.mp4

See workflows/CONTEXT.md for the routing table.

Architecture

mcp_video/
  client/                # Python Client API (mixins per domain)
  client/meta.py         # Client discovery mixin (search_tools)
  server.py              # MCP server (87 tools + 4 resources + search_tools meta-tool)
  server_tools_*.py      # Tool registration by category
  engine.py              # Core FFmpeg engine
  engine_*.py            # Specialized engines (thumbnail, edit, probe, etc.)
  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)
  hyperframes_engine.py  # Hyperframes CLI wrapper
  hyperframes_engine.py  # Hyperframes CLI wrapper
  image_engine.py        # Image color analysis
  quality_guardrails.py  # Automated quality checks
workflows/               # ICM staged pipelines
  CONTEXT.md             # Layer 1 routing table
  01-social-media-clip/  # Stage contract + runnable script
  02-podcast-clip/       # Stage contract + runnable script
  03-explainer-video/    # Stage contract + runnable script

Supported Formats

Agent Discovery

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

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

Community & Support

• 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

Testing

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

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

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

License

Apache 2.0 — see LICENSE.

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

See docs/LEGAL_REVIEW.md for dependency licensing notes.