OSS · Servidor MCP · TypeScript

opencut-mcp

Los editores de video no traen un anclaje para automatización. Este servidor crea uno.

Un servidor Model Context Protocol que maneja OpenCut classic desde Claude Code, Cline o cualquier cliente MCP. Playwright mantiene la sesión del editor; doce herramientas exponen la línea de tiempo, los assets de medios y el pipeline de exportación.

Ver en GitHub Notas de v0.1.0

Claude manejando OpenCut classic vía opencut-mcp: crea proyecto, sube video y audio, coloca ambos en la línea de tiempo, corta el video a los 5 segundos. Todo por llamadas MCP.
Corrida completa de 10 segundos: crear proyecto → subir video → subir audio → auto-placement en pistas separadas → split a los 5s. Cero clics manuales, solo invocaciones MCP.

Doce herramientas MCP

Wrappers 1 a 1 sobre TimelineManager / MediaManager / RendererManager en el navegador. Toda mutación de la línea de tiempo pasa por CommandManager, así que undo/redo funciona sin esfuerzo.

Herramienta Qué hace
opencut_get_state Timeline snapshot (tracks, elements, media assets, total duration).
opencut_add_media Upload a local file as a MediaAsset via the hidden file input.
opencut_insert_clip Place an element on a track. Auto-placement creates the track on demand.
opencut_split_at Split element(s) at a time (seconds). Undoable via opencut_undo.
opencut_move Move an element to a new start time or a different track.
opencut_trim Update trim/duration on an element.
opencut_delete Delete element(s).
opencut_add_track Add a track explicitly (rarely needed — prefer auto placement).
opencut_undo / opencut_redo CommandManager history navigation.
opencut_export RendererManager.exportProject, awaited to completion.
opencut_screenshot Screenshot the editor viewport (debugging).

Corriendo localmente

Dos shells en paralelo: el fork del classic sirve el editor, opencut-mcp se conecta por stdio MCP.

# 1. Fork of OpenCut classic (editor host, port 3000)
git clone https://github.com/kenimo49/opencut-classic
cd opencut-classic
docker compose up -d db redis serverless-redis-http
bun install
bun run dev:web

# 2. opencut-mcp (in another shell)
git clone https://github.com/kenimo49/opencut-mcp
cd opencut-mcp
bun install
bunx tsx src/index.ts      # stdio transport, ready for MCP client
# ...or run the demo:
bunx tsx scripts/demo.ts

Cuatro cosas que no estaban en la documentación

Cada una costó una ronda de debug. Las dejo documentadas para que el próximo lector las salte directo.

  1. Las pistas vacías se eliminan en cada comando

    Un reactor de CommandManager en core/index.ts filtra las pistas de overlay/audio con cero elementos después de cada comando. Una secuencia de dos pasos "addTrack luego insertElement" pierde la pista antes de la segunda llamada. La solución es insertar con placement { mode: "auto", trackType } — el comando de insert crea la pista bajo demanda y sobrevive porque tiene un elemento.

  2. MediaTime son ticks enteros, no segundos

    Los campos de tiempo en TimelineElement (startTime, duration, trimStart, trimEnd, sourceDuration) son enteros con brand type; TICKS_PER_SECOND vale 120000. Pasar 15.008 directo hace que requireMediaTime() lance. Convertí con window.__opencut.mediaTimeFromSeconds({ seconds }) en la frontera del navegador.

  3. AudioElement es una unión discriminada

    El audio subido tiene que llevar sourceType: "upload" junto con mediaId. Sin eso, InsertElementCommand.validateElementBasics rechaza en silencio vía console.error y sigue. Capturá el canal de consola para ver el mensaje — el CommandManager como tal no lanza.

  4. El <input type="file"> de Import está siempre en el DOM, solo con display:none

    useFileUpload siempre renderiza un <input type="file"> oculto. Playwright puede llamar setInputFiles directo — no hace falta clickear el botón Import primero. Eso salta todo el camino de drag-and-drop y aterriza en el mismo lugar donde la UI terminaría.

Herramientas relacionadas para devs

Todos los productos →

← Volver a productos