OSS · Servidor MCP · TypeScript

opencut-mcp

Editores de vídeo não vêm com um encaixe de automação. Este servidor cria um.

Um servidor Model Context Protocol que controla o OpenCut classic a partir do Claude Code, Cline ou qualquer cliente MCP. O Playwright mantém a sessão do editor; doze ferramentas expõem a timeline, os assets de mídia e o pipeline de exportação.

Ver no GitHub Notas da v0.1.0

Claude controlando o OpenCut classic via opencut-mcp — cria projeto, sobe vídeo e áudio, coloca ambos na timeline, corta o vídeo em 5 segundos. Tudo por chamadas MCP.
Execução completa em 10 segundos: criar projeto → upload de vídeo → upload de áudio → auto-placement em trilhas separadas → split em 5s. Zero cliques manuais, só invocações MCP.

Doze ferramentas MCP

Wrappers 1 para 1 sobre TimelineManager / MediaManager / RendererManager no navegador. Toda mutação da timeline passa pelo CommandManager, então undo/redo funciona sem esforço.

Ferramenta O que faz
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).

Rodando localmente

Dois shells lado a lado: o fork do classic serve o editor, o opencut-mcp conecta via 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

Quatro coisas que não estavam na documentação

Cada uma custou uma rodada de debug. Deixei documentado para quem for ler depois pular direto.

  1. Trilhas vazias são removidas a cada comando

    Um reactor do CommandManager em core/index.ts filtra as trilhas de overlay/áudio sem elementos após cada comando. Uma sequência de duas etapas "addTrack depois insertElement" perde a trilha antes da segunda chamada. A saída é inserir com placement { mode: "auto", trackType } — o comando de insert cria a trilha sob demanda e ela sobrevive porque tem um elemento.

  2. MediaTime é contagem inteira de ticks, não segundos

    Os campos de tempo em TimelineElement (startTime, duration, trimStart, trimEnd, sourceDuration) são inteiros marcados com brand type; TICKS_PER_SECOND vale 120000. Passar 15.008 diretamente faz o requireMediaTime() lançar erro. Converta com window.__opencut.mediaTimeFromSeconds({ seconds }) na fronteira do navegador.

  3. AudioElement é uma união discriminada

    Áudio de upload precisa carregar sourceType: "upload" junto com mediaId. Sem isso, InsertElementCommand.validateElementBasics silenciosamente rejeita via console.error e segue. Capture o canal do console para ver a mensagem — o CommandManager em si não lança.

  4. O <input type="file"> do Import fica sempre no DOM, só com display:none

    O useFileUpload sempre renderiza um <input type="file"> escondido. O Playwright consegue chamar setInputFiles direto — não precisa clicar no botão Import antes. Isso pula todo o caminho de drag-and-drop e chega no mesmo lugar que a UI acabaria acionando.

Ferramentas relacionadas para devs

Todos os produtos →

← Voltar para produtos