Descubrimiento público

mcp-video es un servidor MCP, una biblioteca de Python y una CLI para la edición de vídeo mediante agentes. Ayuda a los agentes de IA y a los scripts de automatización a inspeccionar, recortar, fusionar, subtitular, cambiar el tamaño, transcodificar, analizar y generar vídeo con FFmpeg y flujos de trabajo de creación basados en código.

Búsquedas más frecuentes: servidor MCP de edición de vídeo, edición de vídeo para agentes de IA, automatización con FFmpeg, herramientas de vídeo para Claude, vídeo MCP para Cursor, biblioteca de edición de vídeo en Python, canalización de medios para agentes, CLI de automatización de vídeo.

¿Qué es mcp-video?

Un servidor de edición de vídeo de código abierto construido sobre el Model Context Protocol (MCP). Ofrece a los agentes de IA, desarrolladores y creadores de vídeo la capacidad de editar y crear archivos de vídeo mediante programación.

Dos modos:

Editar vídeo existente con FFmpeg: recortar, fusionar, superponer texto, añadir audio, aplicar filtros, estabilizar, detectar escenas, transcribir y más.
Crear vídeo nuevo desde código con Hyperframes (nativo de HTML, Apache 2.0): crear composiciones, previsualizar en vivo, renderizar a MP4 y luego realizar postprocesamiento.

Tres interfaces:

Interfaz	Ideal para	Ejemplo
Servidor MCP	Agentes de IA (Claude Code, Cursor)	"Recorta este vídeo y añade un título"
Cliente Python	Scripts, automatización, canalizaciones	`editor.trim("v.mp4", start="0:30", duration="15")`
CLI	Scripts de shell, operaciones rápidas, humanos	`mcp-video trim video.mp4 -s 0:30 -d 15`

Instalación

Requisitos previos: FFmpeg debe estar instalado. Para las funciones de Hyperframes, también necesitas Node.js 22+.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Instalación:

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

Verifica tu configuración:

mcp-video doctor
mcp-video doctor --json

Inicio rápido

Como servidor MCP (para agentes de IA)

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

Luego simplemente pídele a tu agente: "Recorta este vídeo de 0:30 a 1:00, añade una tarjeta de título y cambia el tamaño para TikTok."

Como biblioteca de Python

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

Flujo de trabajo en Python seguro para agentes

Para agentes autónomos, prefiere la inspección, el encadenamiento de canalizaciones y un punto de control de lanzamiento:

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

Contrato del agente:

Las llamadas del cliente que producen medios devuelven EditResult con .output_path.
Las llamadas de análisis/descubrimiento devuelven informes tipados o diccionarios.
Client.inspect(name) expone parámetros, alias, categoría y tipo de retorno.
Los errores inesperados de palabras clave se convierten en orientación procesable de MCPVideoError.
No publiques vídeos generados por agentes sin assert_quality() o release_checkpoint() además de una inspección visual/auditiva humana.

Como herramienta CLI

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

Herramientas MCP

87 herramientas MCP en 10 categorías, incluida la meta-herramienta search_tools para un descubrimiento rápido. Todas devuelven JSON estructurado. Consulta la referencia completa de herramientas para obtener todos los detalles.

Categoría	Cantidad	Destacados
Vídeo principal	32	recortar, fusionar, texto, audio, redimensionar, convertir, filtros, estabilizar, croma, subtítulos, marca de agua, lote, limpieza, vista previa de plantilla, exportar
Impulsado por IA	11	transcribir (Whisper), detección de escenas, separación de pistas (Demucs), escalado, gradación de color
Hyperframes	8	iniciar, renderizar, imagen fija, vista previa, composiciones, validar, añadir bloque, canalización
Síntesis de audio	7	generar formas de onda, preajustes, secuencias, efectos, audio espacial — NumPy puro
Efectos visuales	8	viñeta, aberración cromática, líneas de escaneo, ruido, brillo, clave de luminancia, máscara, máscara de forma
Transiciones	3	glitch, pixelar, morph
Diseño y movimiento	6	cuadrícula, pip, texto animado, contadores, barras de progreso, capítulos automáticos
Análisis	8	detección de escenas, miniatura, vista previa, guion gráfico, comparación de calidad, metadatos, forma de onda, punto de control de lanzamiento
Análisis de imagen	3	extracción de color, generación de paleta, análisis de producto
Meta	1	`search_tools` — búsqueda por palabras clave en todas las herramientas
Recursos	4	prompts, flujos de trabajo, plantillas, ejemplos

Descubrimiento de herramientas:

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

Integración con Hyperframes

Crea vídeos mediante programación con Hyperframes, un marco nativo de HTML para vídeo.

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

Consulta la documentación de Hyperframes y la referencia del cliente de Python.

Cliente Python

from mcp_video import Client
editor = Client()

Consulta la referencia completa del cliente de Python para todos los métodos y tipos de retorno.

Referencia de CLI

mcp-video [command] [options]

Consulta la referencia completa de CLI para todos los comandos y opciones.

DSL de línea de tiempo

Para ediciones complejas de múltiples pistas, describe todo en un único objeto JSON:

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

Plantillas

Plantillas preconstruidas para formatos comunes de redes sociales:

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)

Compatible con: TikTok, YouTube Shorts, Instagram Reels/Posts, vídeos de YouTube.

Manejo de errores

Errores estructurados y procesables con sugerencias de corrección automática:

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

Flujos de trabajo

Canalizaciones por etapas al estilo ICM para producciones comunes, con contratos de etapa CONTEXT.md, configuración de fábrica references/ y scripts ejecutables workflow.py.

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

Flujo de trabajo	Etapas	Descripción
`01-social-media-clip`	5	Paisaje → TikTok / Short / Reel
`02-podcast-clip`	6	Destacado con capítulos + subtítulos incrustados
`03-explainer-video`	7	Vídeo explicativo de marca desde cero
`04-hyperframes-video`	5	Crear desde cero con Hyperframes, luego post-procesar

Consulta workflows/CONTEXT.md para la tabla de enrutamiento.

Arquitectura

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

Formatos compatibles

Vídeo	Audio (extracción)	Subtítulos
MP4, WebM, MOV, GIF	MP3, AAC, WAV, OGG, FLAC	SRT, WebVTT

Descubrimiento de agentes

llms.txt — mapa compacto del proyecto para agentes
docs/AI_AGENT_DISCOVERY.md — posicionamiento más rico y fragmentos de integración

Desarrollo

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

Comunidad y soporte

Contribución: CONTRIBUTING.md
Seguridad: SECURITY.md (ruta de informe privado)
Ayuda: SUPPORT.md o GitHub Discussions
Código de conducta: CODE_OF_CONDUCT.md
Registro de cambios: CHANGELOG.md
Hoja de ruta: ROADMAP.md
Gobernanza: GOVERNANCE.md
Mantenedores: MAINTAINERS.md

Pruebas

Las pruebas están excluidas del paquete PyPI. Para ejecutar localmente:

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

Consulta docs/TESTING.md para conocer las categorías completas de pruebas y los detalles de CI.

Licencia

Apache 2.0 — consulta LICENSE.

Construido sobre FFmpeg, Hyperframes y el Model Context Protocol.

Consulta docs/LEGAL_REVIEW.md para notas sobre licencias de dependencias.

pastorsimon1798/mcp-video