vidmagik-mcp

vidMagik-mcp

Un servidor de Model Context Protocol (MCP) que proporciona una interfaz integral para MoviePy para edición de video. Utiliza transporte stdio por defecto para una integración perfecta con clientes MCP.

Expone más de 70 herramientas para edición de video de nivel profesional, composición, efectos y procesamiento de audio.

Características

IO y Creación

• Cargar: video_file_clip, audio_file_clip, image_clip, image_sequence_clip
• Generar: text_clip, color_clip, credits_clip, subtitles_clip, tools_drawing_color_gradient, tools_drawing_color_split
• Exportar: write_videofile, write_audiofile, write_gif
• Herramientas rápidas: tools_ffmpeg_extract_subclip (recorte sin pérdida)

Composición y Transformación

• Combinar: composite_video_clips, concatenate_video_clips, tools_clips_array, composite_audio_clips, concatenate_audio_clips
• Refinar: subclip, vfx_resize, vfx_crop, vfx_rotate
• Configurar: set_position, set_audio, set_mask, set_start, set_end, set_duration

Efectos de Video (vfx)

• Tiempo: vfx_freeze, vfx_freeze_region, vfx_multiply_speed, vfx_time_mirror, vfx_time_symmetrize, vfx_loop, vfx_make_loopable, vfx_accel_decel
• Color: vfx_black_white, vfx_invert_colors, vfx_fade_in, vfx_fade_out, vfx_gamma_correction, vfx_lum_contrast, vfx_multiply_color, vfx_painting, vfx_blink
• Geometría: vfx_mirror_x, vfx_mirror_y, vfx_even_size, vfx_margin, vfx_scroll, vfx_supersample
• Movimiento: vfx_slide_in, vfx_slide_out, vfx_head_blur
• Enmascarado: vfx_mask_color, vfx_masks_and, vfx_masks_or

Efectos Avanzados Personalizados

• vfx_matrix — Superposición clásica de "Matrix" con lluvia digital
• vfx_kaleidoscope — Simetría radial con secciones personalizadas
• vfx_rgb_sync — Aberración cromática / glitch con desplazamientos temporales
• vfx_chroma_key — Eliminación de pantalla verde con umbral y suavizado
• vfx_auto_framing — Seguimiento y recorte de rostro/sujeto para video vertical
• vfx_clone_grid — Diseño de cuadrícula multi-clon (2x2, 4x4, etc.)
• vfx_rotating_cube — Mapeo de cubo con perspectiva 3D
• vfx_quad_mirror — Simetría de espejo cuádruple
• vfx_kaleidoscope_cube — Simetría radial combinada con rotación 3D

Efectos de Audio (afx)

• afx_multiply_volume, afx_multiply_stereo_volume, afx_audio_fade_in, afx_audio_fade_out, afx_audio_delay, afx_audio_loop, afx_audio_normalize

Análisis y Utilidades

• tools_detect_scenes — Detección automática de cortes de escena
• tools_find_video_period — Análisis de frecuencia para movimiento repetitivo
• tools_find_audio_period — Detección de tempo/período para audio
• tools_file_to_subtitles — Analizar archivos de subtítulos
• tools_check_installation — Verificar MoviePy y dependencias

Requisitos Previos

• Python 3.12+
• FFmpeg — Requerido por MoviePy para procesamiento de video
• ImageMagick — Requerido para text_clip y credits_clip
• uv — Gestor de paquetes de Python

Instalación

git clone https://github.com/vizionik25/vidMagik-mcp.git
cd vidMagik-mcp
uv sync

Ejecutar el Servidor

El servidor utiliza transporte stdio por defecto:

uv run main.py

Para usar transporte HTTP o SSE en su lugar:

uv run main.py --transport http --host 0.0.0.0 --port 8080
uv run main.py --transport sse --host 0.0.0.0 --port 8080

Configuración del Cliente MCP

Agregue esto a la configuración de su cliente MCP (por ejemplo, Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "vidMagik-mcp": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "/path/to/vidMagik-mcp"
    }
  }
}

Docker

Docker es el enfoque recomendado: incluye FFmpeg, ImageMagick y todas las dependencias del sistema automáticamente.

Inicio Rápido

docker compose up --build

Esto construye la imagen e inicia el servidor con transporte stdio.

Directorio de Medios

El directorio ./media en su host se monta en /app/media dentro del contenedor. Úselo como espacio de trabajo para todos los archivos de entrada y salida:

mkdir -p media
# Place your source videos, images, and audio in ./media

Al usar herramientas MCP, haga referencia a los archivos como media/filename.mp4. Los archivos de salida escritos en media/ aparecerán en su host.

Configuración del Cliente MCP con Docker

Para usar el contenedor Docker como servidor MCP:

{
  "mcpServers": {
    "moviepy": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-i", "mcp-moviepy"],
      "cwd": "/path/to/mcp-moviepy"
    }
  }
}

Compilación y Ejecución Manual de Docker

docker build -t mcp-moviepy .
docker run -i -v $(pwd)/media:/app/media mcp-moviepy

Gestión de Estado

El servidor mantiene clips en memoria:

1. IDs de Clip — Las herramientas que crean o modifican clips devuelven un clip_id (cadena UUID)
2. Encadenamiento — Pase clip_id a herramientas posteriores para operaciones adicionales
3. Gestión — Use list_clips para ver clips activos y delete_clip para liberar memoria
4. Límites — Limpieza automática de memoria con límites de recuento de archivos y tamaño total para prevenir OOM

Plantillas de Prompt

Los prompts integrados guían al LLM a través de flujos de trabajo complejos:

• slideshow_wizard — Presentación de diapositivas profesional a partir de imágenes con transiciones
• title_card_generator — Tarjetas de título con texto sobre fondos sólidos
• glitch_effect_preset — Estética glitch de alta energía con división RGB
• auto_framing_for_tiktok — Convertir video horizontal a vertical 9:16
• matrix_intro_preset — Superposición clásica de lluvia de código
• rotating_cube_transition — Efecto de cubo giratorio 3D
• demonstrate_kaleidoscope — Animación hipnotizante de simetría radial
• demonstrate_kaleidoscope_cube — Cubo 3D híbrido con caleidoscopio

Desarrollo

Ejecutar pruebas:

uv run pytest tests/test_e2e.py

Licencia

MIT