videolab-mcp

Un servidor MCP que convierte a Claude (o cualquier host MCP) en un editor de vídeo práctico para vídeos de formato corto. Explora una biblioteca de música o genera nuevas pistas. Anima imágenes fijas con Veo o sincroniza los labios de retratos con OmniHuman. Escribe y reescribe guiones. Sintetiza voz en off con ElevenLabs. Monta la línea de tiempo con FFmpeg, reproduce el resultado y luego itera de forma económica intercambiando la música, la voz en off o cualquier clip individual, sin necesidad de volver a renderizar desde cero.

También incluye una función de texto a documental que convierte textos largos (PDFs, libros, artículos) en vídeos documentales estructurados con voz en off generada por IA, subtítulos y material de archivo (b-roll).

Independiente, portátil y configurable. Trae tus propias claves de API.

Qué incluye

Herramientas a lo largo del flujo de trabajo:

Recursos para navegar sin consumir llamadas a herramientas: library://music, library://broll, library://renders, library://voiceovers, library://scripts, library://scenes.

Prompts para flujos guiados de varios pasos: make-scene-promo, remix-render, compose-music-for-scene.

Habilidades en skills/: text-to-documentary — PDF/libro → vídeos documentales por capítulos con arcos narrativos estructurados.

Related MCP server: Video MCP

Requisitos

• Node.js 18+

• FFmpeg en tu PATH (o establece ffmpeg.binary a una ruta absoluta en la configuración)

• Claves de API para los proveedores que utilices (no se requieren de antemano; la inicialización es perezosa solo en la primera llamada)

Inicio rápido

git clone <this-repo> videolab-mcp
cd videolab-mcp
npm install
npm run build
cp videolab.config.example.json videolab.config.json
cp .env.example .env  # then fill in keys you have

Conéctalo a Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %AppData%\Claude\claude_desktop_config.json en Windows):

{
  "mcpServers": {
    "videolab": {
      "command": "node",
      "args": ["C:\\path\\to\\videolab-mcp\\build\\index.js"],
      "env": {
        "ELEVENLABS_API_KEY": "...",
        "ANTHROPIC_API_KEY": "...",
        "GOOGLE_VEO_API_KEY": "...",
        "FAL_KEY": "...",
        "VIDEOLAB_CONFIG": "C:\\path\\to\\videolab-mcp\\videolab.config.json"
      }
    }
  }
}

Reinicia Claude Desktop. Abre un chat y llama a ping para confirmar la conexión.

Configuración

Dos archivos. .env solo para secretos:

ELEVENLABS_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_VEO_API_KEY=
FAL_KEY=

videolab.config.json para todo lo demás (almacenamiento, proveedores, flags de FFmpeg, valores predeterminados). El archivo de ejemplo es sensato y no tiene dependencias: almacenamiento local, índice JSON, proveedores ElevenLabs/Anthropic/Veo/Fal, valores predeterminados para móvil (9:16).

Tutorial: crea una promo desde cero

En Claude Desktop, con el servidor MCP conectado:

User: Make a 20-second mobile promo for the test scene.

Claude:
  → list_scene_assets({ sceneRef: { key: "test-scene" } })
     → 3 assets: magenta, cyan, orange

  → generate_script({
      context: "Test scene with three coloured backdrops",
      durationSeconds: 20, tone: "punchy"
    })
     → scriptId: script_a3f, slot breakdown shown

  → generate_voiceover({ text: "<the script>" })
     → voiceoverId: vo_8d2

  → generate_music({
      prompt: "driving electronic, slow build, retro synth pad",
      durationMs: 20000
    })
     → trackId: music_4e1

  → assemble_promo({
      timeline: {
        platform: "mobile",
        slots: [
          { source: { kind: "scene", id: "asset-test-magenta" }, durationMs: 7000 },
          { source: { kind: "scene", id: "asset-test-cyan" },    durationMs: 7000 },
          { source: { kind: "scene", id: "asset-test-orange" },  durationMs: 6000 }
        ]
      },
      voiceoverId: "vo_8d2",
      musicId: "music_4e1"
    })
     → renderId: render_94c, autoplays in default video player

User: Make the music more chill.

Claude:
  → generate_music({ prompt: "soft ambient pad, gentle rhythm", durationMs: 20000 })
     → trackId: music_c70
  → swap_music({ renderId: "render_94c", newMusicId: "music_c70" })
     → renderId: render_d11 (rev of render_94c) — only re-mixes audio (~2s)

User: Replace the orange shot with a Veo animation of the magenta image zooming in.

Claude:
  → animate_image_to_video({
      imageSource: { kind: "scene", id: "asset-test-magenta" },
      prompt: "slow camera push-in, dust particles drifting"
    })
     → clipId: broll_veo_a8b
  → swap_clip({
      renderId: "render_d11",
      slotIndex: 2,
      newSource: { kind: "broll", id: "broll_veo_a8b" }
    })
     → renderId: render_2f9 (rev of render_d11)

El bucle de iteración

Esta es la parte que hace que el flujo de trabajo se sienta bien:

• assemble_promo escribe intermedios por ranura (slot_*.mp4), un visuals.mp4 silencioso, la mezcla de audio y el output.mp4 final, todo bajo media/renders/<renderId>/.

• swap_music / swap_voiceover reutilizan el visuals.mp4 del padre y solo vuelven a mezclar el audio. Tiempo típico: ~2 segundos.

• swap_clip reconstruye el flujo de visuales + remezcla el audio. Tiempo típico: ~5–10 segundos.

• Cada renderizado es un nuevo renderId vinculado a través de parentId: nunca pierdes una versión anterior.

Modo texto a documental

La habilidad skills/text-to-documentary/ convierte un PDF, libro o texto largo pegado en una serie de vídeos documentales de ~5 minutos, uno por capítulo. Cada vídeo tiene un arco narrativo estructurado (Gancho → Idea central → Ejemplos → Interrupciones de patrón → Micro-resúmenes → Suspenso), subtítulos tipo karaoke a partir de marcas de tiempo de alineación de ElevenLabs y material de archivo generado por IA.

Herramientas utilizadas: extract_pdf, split_chapters, plan_documentary_scenes, validate_attention, generate_voiceover, generate_image, animate_image_to_video, generate_music, assemble_promo.

Si utilizas Claude Code u otro host que admita habilidades, la habilidad se carga automáticamente cuando se activa ("convierte este PDF en un documental", "haz vídeos de este libro", etc.). De lo contrario, lee skills/text-to-documentary/SKILL.md para ver la lista completa de pasos y llama a las herramientas directamente.

Proveedor de recursos de escena personalizado

El servidor es agnóstico respecto al proveedor de recursos de escena. El proveedor json-manifest incluido lee desde un archivo JSON. Cualquier cosa más elaborada (tu CMS, una base de datos, una API) se implementa como un SceneAssetProvider:

export interface SceneAssetProvider {
  readonly kind: string;
  describeRefShape(): string;  // shows up in the tool description so the host knows what to send
  listAssets(ref: SceneRef): Promise<SceneAsset[]>;
  getAsset(id: string): Promise<SceneAsset | null>;
}

Coloca tu implementación en src/providers/scene-assets/<tu-nombre>.ts, regístrala en src/providers/factory.ts bajo buildSceneAssets y añádela al esquema de configuración en src/config.ts. El mismo patrón funciona para los backends de almacenamiento (S3, Azure): consulta src/providers/types.ts:StorageProvider.

Matriz de proveedores

Anulaciones de modelo opcionales mediante entorno: ANTHROPIC_MODEL, ELEVENLABS_MUSIC_MODEL, VEO_MODEL, VEO_ENDPOINT, VEO_POLL_INTERVAL_MS, VEO_POLL_TIMEOUT_MS, FAL_OMNIHUMAN_MODEL, PROMO_VIDEO_LOG_LEVEL.

Licencia

MIT: consulta LICENSE.