ffmpeg-mcp

Un paquete de Python para procesamiento multimedia utilizando FFmpeg y FastMCP.

GitHub
11
Prueba este MCPPatrocinado

Documentación

ffmpeg-mcp

ffmpeg-mcp 🎬⚡

Edita video y audio simplemente hablando con tu asistente de IA.

ffmpeg-mcp es un servidor de Model Context Protocol que pone todo el poder de FFmpeg detrás de un conjunto limpio de herramientas que tu LLM puede invocar: recortar, cortar, escalar, superponer, concatenar con transiciones, extraer fotogramas/audio, crear GIFs y más. Sin banderas de línea de comandos que memorizar.

Python FastMCP FFmpeg PRs Welcome Stars

✨ ¿Por qué ffmpeg-mcp?

FFmpeg es increíblemente potente e increíblemente difícil de recordar. ffmpeg-mcp pone ese poder en manos de tu asistente de IA para que puedas decir lo que quieras en lenguaje natural:

"Toma los primeros 10 segundos de demo.mov, escálalo a 1080p, coloca mi logo en la esquina superior derecha y conviértelo en un GIF."

…y el modelo orquesta las herramientas adecuadas para ti. Cada herramienta es una pequeña función de Python validada: fácil de leer, reutilizar y ampliar.

  • 🗣️ Edición de video en lenguaje natural — funciona en cualquier cliente MCP (Claude Desktop, Cursor, Cline, …)
  • 🧱 12 herramientas enfocadas — bloques de construcción componibles en lugar de una caja negra gigante
  • ✅ Validación de entrada integrada — las rutas se verifican por existencia, vacío y validez antes de que FFmpeg se ejecute
  • 🧩 Extensible — añade una nueva herramienta escribiendo una función y registrándola

🛠️ Herramientas disponibles

HerramientaQué haceParámetros clave
get_video_metadataInspecciona un archivo para streams, códecs, duración, etc.input_video_path
extract_framesGuarda fotogramas como imágenes (uniformemente, por intervalo, o 1/seg)input_video_path, number_of_frames?, timestamp_offset?
extract_audioExtrae el audio a un archivo .wavinput_video_path
scale_videoEscala a 1080p / 2k / 4k, preservando la relación de aspectoinput_video_path, resolution="1080p"
crop_videoRecorta a una regióninput_video_path, width, height, x_offset, y_offset, safe_crop
clip_videoCorta un subclip por inicio + duracióninput_video_path, start_timestamp, duration
make_gifConvierte un segmento en un GIF optimizadoinput_video_path, start_timestamp, duration
overlay_imageCompone una imagen (logo/marca de agua) con sincronización y opacidadinput_video_path, overlay_image_path, positioning, opacity, start_time, duration
overlays_videoSuperpone un video (en bucle) sobre otroinput_video_path, overlay_video_path, positioning, scale
trim_and_concat_operationRecorta varios clips y los uneinputs: [{path, start_time?, end_time?}], width, height
get_normalized_clipsNormaliza clips a una resolución/fps/códec común (en paralelo)input_video_clips, resolution, frame_rate, crf
concat_clips_with_transitionConcatena clips con una transición xfadeinput_video_clips, transition_type="fade", transition_duration

? marca parámetros opcionales. concat_clips_with_transition admite muchas transiciones: fade, wipeleft, slideup, circlecrop, dissolve, pixelize, radial y docenas más.

📦 Requisitos

  • Python 3.12+
  • FFmpeg instalado y en tu PATH (proporciona ffmpeg + ffprobe)
  • uv gestor de paquetes

Verifica que FFmpeg esté disponible:

ffmpeg -version

🚀 Inicio rápido

1. Clona e instala

git clone https://github.com/yubraaj11/ffmpeg-mcp.git
cd ffmpeg-mcp
uv sync --frozen

2. Conéctalo a tu cliente MCP

Apunta tu cliente al servidor usando los fragmentos siguientes. Reemplaza /path/to/ffmpeg-mcp con la ruta absoluta a tu clon.

Claude Desktop / Cursor (claude_desktop_config.json o .cursor/mcp.json) 
{
  "mcpServers": {
    "ffmpeg-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ffmpeg-mcp/ffmpeg_mcp", "run", "main.py"],
      "env": { "PYTHONPATH": "/path/to/ffmpeg-mcp" }
    }
  }
}
Cline (VS Code) 
{
  "mcpServers": {
    "ffmpeg-mcp": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "command": "uv",
      "args": ["--directory", "/path/to/ffmpeg-mcp/ffmpeg_mcp", "run", "main.py"],
      "env": { "PYTHONPATH": "/path/to/ffmpeg-mcp" },
      "transportType": "stdio"
    }
  }
}

3. Reinicia tu cliente y empieza a editar

"Extrae 5 fotogramas espaciados uniformemente de intro.mp4."

"Crea un GIF de 3 segundos desde clip.mov comenzando en el segundo 12."

"Concatena a.mp4, b.mp4 y c.mp4 con una transición wipeleft de 1 segundo entre ellos."

Los archivos procesados se escriben en ffmpeg_mcp/processed_elements/.

🧰 Estructura del proyecto

ffmpeg_mcp/
├── main.py              # MCP server entry point — registers all tools
├── services/            # one module per tool
├── configs/             # colored logging setup
└── exceptions/          # structured error messages
utils/                   # validation decorators & helpers

Cada herramienta devuelve la ruta del archivo de salida o un error JSON estructurado (status, error_type, message, time), de modo que los fallos son fáciles de leer y recuperar para el modelo.

🤝 Contribuciones

¡Las contribuciones son muy bienvenidas! Añadir una herramienta es aproximadamente:

  1. Escribe una función en ffmpeg_mcp/services/your_tool.py.
  2. Expórtala desde ffmpeg_mcp/services/__init__.py.
  3. Regístrala en main.py con mcp.tool(name_or_fn=your_tool).

Por favor, ejecuta el linter antes de abrir un PR:

uv run ruff check .

¿Encontraste un error o tienes una idea? Abre un issue — y si este proyecto te salva de otra inmersión en la página de manual de ffmpeg, considera dejar una ⭐.

📚 Construido con