Servidor MCP de Producción de Video Remotion

Un servidor de Model Context Protocol (MCP) de primer nivel que actúa como un puente inteligente para que los agentes de IA analicen ritmos de audio, sinteticen voces con Google Gemini TTS y construyan y rendericen videos profesionales de forma programática usando Remotion (v4.0+) y React.

Soporta AMBOS:

• 💻 Transporte STDIO Local: Para clientes de IA locales (Antigravity, Claude Desktop, Cursor).

• 🌐 Transporte HTTP Streamable Remoto: Para despliegues en la nube (Render) y clientes de IA basados en web (Claude Web en https://claude.ai/new).

🚀 Características Clave

• 🎬 Andamiaje Programático: Crea proyectos de video React/Remotion con configuración cero y relaciones de aspecto integradas: TikTok/Reels (tiktok-916), YouTube (youtube-169) y Social (social-11).

• 🎙️ Integración con Gemini 3.1 Flash TTS: Genera diálogos de escenas con voz de alta fidelidad y acentos regionales, y produce códigos de tiempo a nivel de palabra para subtítulos cinéticos.

• 🎵 Sincronización de Ritmo de Audio con Librosa: Analiza música de fondo para extraer BPM, límites de ritmo, caídas/subidas de energía RMS y recomendar cortes de escena con precisión de fotogramas.

• 📸 Instantáneas de Vista Previa Visual: Renderiza instantáneamente capturas de fotogramas (PNG/JPEG/WebP) en cualquier índice de fotograma para verificación visual por IA.

• ⚡ Renderizado sin Interfaz: Compila programáticamente videos MP4/WebM de alta calidad con control de concurrencia multinúcleo y seguimiento de progreso.

• 🔒 Autenticación con Token Bearer: Asegura tus endpoints MCP HTTP cuando se despliegan en servicios de nube públicos.

Related MCP server: atsurae

🛠️ Requisitos Previos

Para ejecutar este servidor MCP y renderizar videos, el entorno anfitrión requiere:

1. Node.js (v20.0.0 o superior recomendado) y npm.

2. Python 3 (v3.10+ recomendado) con paquetes de audio instalados:

   pip install librosa numpy scipy google-genai

3. Dependencias del Navegador de Remotion: Lanzar Chrome sin interfaz requiere Chromium. Instálalo mediante CLI:

   npx @remotion/cli browser ensure

🌐 MCP Remoto / Claude Web y Despliegue HTTP Streamable

Este servidor soporta la Especificación de Transporte HTTP Streamable MCP (@modelcontextprotocol/sdk v1.29.0), lo que permite que clientes basados en web como Claude Web (https://claude.ai/new) se conecten de forma remota.

1. Ejecutar el Servidor HTTP Localmente

Compila e inicia el servidor HTTP Streamable:

npm install
npm run build
npm run start:http

Por defecto, el servidor escucha en:

• Verificación de Salud: GET http://localhost:3000/health

• Endpoint MCP: http://localhost:3000/mcp

2. Variables de Entorno

Crea un archivo .env o exporta las variables de entorno:

3. Asegurar el Endpoint MCP HTTP

Al desplegar en un servidor público, configura MCP_AUTH_TOKEN:

export MCP_AUTH_TOKEN=your-secret-token-here
npm run start:http

Las solicitudes entrantes a /mcp deben incluir el encabezado:

Authorization: Bearer your-secret-token-here

Las solicitudes que falten o especifiquen un token inválido recibirán una respuesta 401 Unauthorized.

4. Probar los Endpoints HTTP y de Salud

• Verificar el Estado de Salud:

  curl http://localhost:3000/health
  # Response: {"status":"ok","service":"remotion-mcp-server"}

• Verificar la Inicialización MCP:

  curl -X POST http://localhost:3000/mcp \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your-secret-token-here" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "initialize",
      "params": {
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": { "name": "curl-test", "version": "1.0.0" }
      }
    }'

5. Despliegue en Render (Un Clic / Blueprint)

El repositorio incluye un blueprint render.yaml y un Dockerfile listo para producción que empaqueta Node 20, Chromium, FFmpeg y bibliotecas de audio de Python.

1. Sube tu repositorio a GitHub.

2. Inicia sesión en Render y haz clic en Nuevo + -> Blueprint.

3. Conecta tu repositorio (remotionMcpServer). Render detectará automáticamente render.yaml.

4. Configura las variables de entorno en el Panel de Render:

   • MCP_AUTH_TOKEN: Tu token secreto personalizado.

   • GEMINI_API_KEY: Tu clave API de Gemini.

5. ¡Despliega! Tu URL MCP remota será:

   https://YOUR-SERVICE-NAME.onrender.com/mcp

6. Conectarse a Claude Web

1. Ve a https://claude.ai/new.

2. Abre la configuración de Conectores MCP Personalizados.

3. Ingresa tu URL MCP remota:

   https://YOUR-SERVICE-NAME.onrender.com/mcp

4. Si la autenticación está habilitada, configura el encabezado Authorization con Bearer <tu-token-mcp-auth>.

5. Guarda y conéctate. Claude Web listará las 5 herramientas de Remotion disponibles.

💻 Configuración STDIO Local (Antigravity y Clientes Locales)

Configuración Instantánea con un Comando (Recomendado)

Copia y pega un solo comando en tu terminal:

🍎 macOS / Linux (Terminal)

curl -fsSL https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.sh | bash

🪟 Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/ivalenzuela/remotion-mcp-server/main/autoinstall.ps1 | iex

Configuración Manual de STDIO

1. Compila el Servidor:

   git clone https://github.com/ivalenzuela/remotion-mcp-server.git
   cd remotion-mcp-server
   npm install
   npm run build

2. Regístrate en el Cliente de IA (mcp_config.json / claude_desktop_config.json):

   {
     "mcpServers": {
       "remotion": {
         "command": "node",
         "args": ["/path/to/remotion-mcp-server/dist/index.js"],
         "env": {
           "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY_HERE"
         }
       }
     }
   }

🤖 Herramientas MCP Disponibles

Las cinco herramientas están disponibles de manera idéntica en los transportes STDIO y HTTP Streamable:

1. remotion_scaffold_project

Crea un proyecto completo de React/Remotion con plantillas preconstruidas, componentes de diseño estándar e instala automáticamente las dependencias de npm.

• Argumentos:

  • projectName (cadena, obligatorio): Nombre de la carpeta del proyecto objetivo.

  • template (enumeración: tiktok-916, youtube-169, social-11, obligatorio): Relación de aspecto.

  • targetDir (cadena, obligatorio): Ruta del directorio padre.

2. remotion_analyze_audio

Realiza procesamiento de señales en archivos de audio usando Python Librosa para devolver BPM, fotogramas de ritmo, perfiles de energía, números de fotogramas de corte de escena recomendados y alinea subtítulos SRT.

• Argumentos:

  • audioPath (cadena, obligatorio): Ruta al archivo de audio de entrada.

  • srtPath (cadena, opcional): Ruta al archivo de subtítulos SRT.

  • outputPath (cadena, opcional): Ruta para guardar el análisis JSON de salida.

  • fps (número, predeterminado 30): Velocidad de fotogramas de la composición objetivo.

  • minSceneDuration (número, predeterminado 3.5): Segundos mínimos entre cortes de escena.

3. remotion_generate_tts

Sintetiza voz usando Google Gemini 3.1 Flash TTS (gemini-3.1-flash-tts-preview) y genera códigos de tiempo de palabras ponderados por carácter. Automáticamente recurre a audio sintético limpio si GEMINI_API_KEY no está presente.

• Argumentos:

  • text (cadena, obligatorio): Texto del diálogo a sintetizar.

  • outputPath (cadena, obligatorio): Ruta para guardar el archivo .wav generado.

  • voice (cadena, predeterminado "Puck"): Nombre de voz preconstruida de Gemini.

  • accent (cadena, opcional): Instrucción opcional de acento regional.

  • fps (número, predeterminado 30): Velocidad de fotogramas.

4. remotion_preview_frame

Renderiza una imagen de instantánea estática (PNG/JPEG/WebP) de un fotograma específico en la composición usando la CLI de Remotion.

• Argumentos:

  • projectDir (cadena, obligatorio): Ruta al proyecto de Remotion.

  • compositionId (cadena, obligatorio): ID de composición objetivo.

  • frame (número, predeterminado 0): Índice de fotograma a capturar.

  • imageFormat (enumeración: png, jpeg, webp, predeterminado png): Formato.

  • props (objeto, opcional): Props de React de entrada.

5. remotion_render_video

Compila una composición en un video de calidad profesional (MP4/WebM).

• Argumentos:

  • projectDir (cadena, obligatorio): Ruta al proyecto de Remotion.

  • compositionId (cadena, obligatorio): ID de composición objetivo.

  • outputPath (cadena, opcional): Ruta de salida del video.

  • concurrency (número/cadena, predeterminado "auto"): Hilos de CPU a utilizar.

  • codec (cadena, predeterminado "h264"): Códec objetivo.

  • props (objeto, opcional): Props de React de entrada.

🎨 Componentes React Preconstruidos

Los proyectos andamiados incluyen estos componentes de diseño listos para producción:

1. SubtitleOverlay: Escalado activo palabra por palabra y resplandores de sombra de texto personalizados ("Efecto Lupa PRO") para subtítulos bilingües.

2. KenBurnsImage: Escalado y traducción de imágenes basados en interpolación limpia sin animaciones CSS.

3. AudioSpectrum: Barras visualizadoras del espectro de frecuencia de sonido sincronizadas reactivamente con la banda sonora.

4. LowerThird: Apariciones elegantes de tercio inferior para perfiles de redes sociales o tarjetas de nombre.

🧪 Pruebas y Verificación

Ejecuta la suite de pruebas E2E completa para verificar la ejecución de herramientas, la resolución de rutas y el renderizado CLI:

npm test

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.