Öffentliche Erkennung

mcp-video ist ein MCP-Server, eine Python-Bibliothek und ein CLI für agentengestützte Videobearbeitung. Es hilft KI-Agenten und Automatisierungsskripten dabei, Videos mit FFmpeg und codebasierten Erstellungs-Workflows zu inspizieren, zu schneiden, zusammenzuführen, zu untertiteln, in der Größe anzupassen, umzuwandeln, zu analysieren und zu generieren.

Suchbegriffe: MCP-Server für Videobearbeitung, KI-Agenten-Videobearbeitung, FFmpeg-Automatisierung, Claude-Videotools, Cursor MCP-Video, Python-Bibliothek für Videobearbeitung, agentengestützte Medien-Pipeline, Video-Automatisierungs-CLI.

Was ist mcp-video?

Ein Open-Source-Server für Videobearbeitung, der auf dem Model Context Protocol (MCP) basiert. Er ermöglicht KI-Agenten, Entwicklern und Videokünstlern, Videodateien programmgesteuert zu bearbeiten und zu erstellen.

Zwei Modi:

Vorhandene Videos bearbeiten mit FFmpeg — schneiden, zusammenführen, Text überlagern, Audio hinzufügen, Filter anwenden, stabilisieren, Szenen erkennen, transkribieren und mehr.
Neue Videos aus Code erstellen mit Hyperframes (HTML-nativ, Apache 2.0) — Kompositionen erstellen, live in der Vorschau ansehen, als MP4 rendern und anschließend nachbearbeiten.

Drei Schnittstellen:

Schnittstelle	Am besten geeignet für	Beispiel
MCP-Server	KI-Agenten (Claude Code, Cursor)	"Schneide dieses Video und füge einen Titel hinzu"
Python-Client	Skripte, Automatisierung, Pipelines	`editor.trim("v.mp4", start="0:30", duration="15")`
CLI	Shell-Skripte, schnelle Vorgänge, Menschen	`mcp-video trim video.mp4 -s 0:30 -d 15`

Installation

Voraussetzungen: FFmpeg muss installiert sein. Für Hyperframes-Funktionen benötigen Sie außerdem Node.js 22+.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Installation:

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

Überprüfen Sie Ihre Einrichtung:

mcp-video doctor
mcp-video doctor --json

Schnellstart

Als MCP-Server (für KI-Agenten)

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

Fragen Sie dann einfach Ihren Agenten: "Schneide dieses Video von 0:30 bis 1:00, füge eine Titelkarte hinzu und passe die Größe für TikTok an."

Als Python-Bibliothek

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

Agentensicherer Python-Workflow

Für autonome Agenten sollten Sie Inspektion, Pipeline-Verkettung und einen Release-Checkpoint bevorzugen:

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

Agenten-Vertrag:

Aufrufe von medienproduzierenden Clients geben EditResult mit .output_path zurück.
Analyse-/Erkennungsaufrufe geben typisierte Berichte oder Wörterbücher zurück.
Client.inspect(name) legt Parameter, Aliase, Kategorie und Rückgabetyp offen.
Rohe Fehler bei unerwarteten Schlüsselwörtern werden in umsetzbare MCPVideoError-Anleitungen umgewandelt.
Veröffentlichen Sie keine von Agenten generierten Videos ohne assert_quality() oder release_checkpoint() sowie eine visuelle/auditive Überprüfung durch Menschen.

Als 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

87 MCP-Tools in 10 Kategorien, einschließlich des Meta-Tools search_tools für eine schnelle Erkennung. Alle geben strukturiertes JSON zurück. Siehe die vollständige Tool-Referenz für alle Details.

Kategorie	Anzahl	Highlights
Core Video	32	trim, merge, text, audio, resize, convert, filters, stabilize, chroma key, subtitles, watermark, batch, cleanup, template preview, export
KI-gestützt	11	transcribe (Whisper), scene detect, stem separation (Demucs), upscale, color grade
Hyperframes	8	init, render, still, preview, compositions, validate, add block, pipeline
Audio-Synthese	7	generate waveforms, presets, sequences, effects, spatial audio — pure NumPy
Visuelle Effekte	8	vignette, chromatic aberration, scanlines, noise, glow, luma key, mask, shape mask
Übergänge	3	glitch, pixelate, morph
Layout & Bewegung	6	grid, pip, animated text, counters, progress bars, auto-chapters
Analyse	8	scene detect, thumbnail, preview, storyboard, quality compare, metadata, waveform, release checkpoint
Bildanalyse	3	color extraction, palette generation, product analysis
Meta	1	`search_tools` — Stichwortsuche über alle Tools hinweg
Ressourcen	4	prompts, workflows, templates, examples

Tool-Erkennung:

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

Hyperframes-Integration

Erstellen Sie Videos programmgesteuert mit Hyperframes — einem HTML-nativen Framework für Videos.

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

Siehe Hyperframes-Dokumentation und die Python-Client-Referenz.

Python-Client

from mcp_video import Client
editor = Client()

Siehe die vollständige Python-Client-Referenz für alle Methoden und Rückgabetypen.

CLI-Referenz

mcp-video [command] [options]

Siehe die vollständige CLI-Referenz für alle Befehle und Optionen.

Timeline-DSL

Für komplexe Multi-Track-Bearbeitungen beschreiben Sie alles in einem einzigen JSON-Objekt:

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

Vorlagen

Vorgefertigte Vorlagen für gängige Social-Media-Formate:

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)

Unterstützt: TikTok, YouTube Shorts, Instagram Reels/Posts, YouTube-Videos.

Fehlerbehandlung

Strukturierte, umsetzbare Fehler mit Vorschlägen zur automatischen Korrektur:

{
  "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-artige gestufte Pipelines für gängige Produktionen — mit CONTEXT.md-Stufenverträgen, references/-Fabrikkonfiguration und ausführbaren workflow.py-Skripten.

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

Workflow	Stufen	Beschreibung
`01-social-media-clip`	5	Querformat → TikTok / Short / Reel
`02-podcast-clip`	6	Highlight mit Kapiteln + eingebrannten Untertiteln
`03-explainer-video`	7	Markenvideo von Grund auf neu
`04-hyperframes-video`	5	Von Grund auf mit Hyperframes erstellen, dann nachbearbeiten

Siehe workflows/CONTEXT.md für die Routing-Tabelle.

Architektur

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

Unterstützte Formate

Video	Audio (Extraktion)	Untertitel
MP4, WebM, MOV, GIF	MP3, AAC, WAV, OGG, FLAC	SRT, WebVTT

Agenten-Erkennung

llms.txt — kompakte Projektkarte für Agenten
docs/AI_AGENT_DISCOVERY.md — reichhaltigere Positionierungs- und Integrations-Snippets

Entwicklung

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

Community & Support

Mitwirken: CONTRIBUTING.md
Sicherheit: SECURITY.md (privater Meldeweg)
Hilfe: SUPPORT.md oder GitHub Discussions
Verhaltenskodex: CODE_OF_CONDUCT.md
Changelog: CHANGELOG.md
Roadmap: ROADMAP.md
Governance: GOVERNANCE.md
Betreuer: MAINTAINERS.md

Testen

Tests sind vom PyPI-Paket ausgeschlossen. Um sie lokal auszuführen:

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

Siehe docs/TESTING.md für vollständige Testkategorien und CI-Details.

Lizenz

Apache 2.0 — siehe LICENSE.

Aufgebaut auf FFmpeg, Hyperframes und dem Model Context Protocol.

Siehe docs/LEGAL_REVIEW.md für Hinweise zur Lizenzierung von Abhängigkeiten.

pastorsimon1798/mcp-video