Davinci Resolve Lua MCP

DaVinci Resolve Lua MCP

Controle a edição gratuita do DaVinci Resolve 21.1 a partir do Claude por meio de um script Lua que roda dentro do Resolve. macOS e Windows (experimental), sem licença Studio, sem rede.

O DaVinci Resolve 21.1 moveu o scripting em Python e a API de scripting externa para a edição Studio, e o próprio servidor MCP da Blackmagic acompanha apenas o Studio. Ainda há uma porta aberta na edição gratuita: o Workspace > Scripts lista e executa arquivos Lua. Este projeto coloca um pequeno script Lua lá. Iniciado uma vez por sessão do Resolve, ele mantém o objeto resolve ativo e executa Lua em nome de um servidor MCP que o Claude Desktop roda como extensão.

[!NOTE] Nada aqui desbloqueia recursos do Studio: a ponte usa a própria API de scripting Lua da edição gratuita. Usuários do Studio 21.1 já têm o servidor MCP nativo da Blackmagic.

Recursos

• 15 ferramentas específicas: visão geral do projeto, listas de projetos e timelines, clipes da Media Pool, itens de timeline, marcadores, alternância de timeline e projeto, renderização com verificação de status e uma busca na referência de scripting fornecida pela Blackmagic.
• run_lua para todo o resto: qualquer trecho Lua 5.1 roda dentro do Resolve com o objeto resolve ativo e retorna JSON, saída capturada de print e erros.
• Um pacote .mcpb: instale-o no Claude Desktop, e o servidor copia seus dois scripts Lua para a pasta de scripts do usuário do Resolve no primeiro início.
• Sem rede: o servidor e o script se comunicam por um arquivo de requisição e pelas preferências do Fusion. Não há sockets, listeners nem telemetria.
• Rápido o suficiente para parecer interativo: cerca de 60 ms por chamada, medido de ponta a ponta em um Mac.

Requisitos

• macOS (Apple Silicon é o único hardware medido).
• Windows 10 ou 11, experimental. Os caminhos padrão vêm da documentação da Blackmagic e de relatos em fóruns; nada foi medido no Windows ainda. docs/windows.md lista o que verificar.
• DaVinci Resolve edição gratuita 21.1 (build 21.1.0.17 é a medida). O Studio não é necessário nem alvo. A Blackmagic não documenta nem este host Lua nem sua sandbox, então uma versão pontual pode mudar o que funciona.
• Claude Desktop. Ele inclui o runtime Node que o servidor precisa (Node 20 ou mais novo); nada mais é instalado.
• Um projeto aberto no Resolve enquanto você usa as ferramentas.

Instalação

1. Baixe o davinci-resolve-lua-mcp.mcpb (a versão mais recente; as notas de versão e o SHA-256 estão na página de Releases).
2. Clique duas vezes no arquivo, ou arraste-o para a janela do Claude Desktop. O Claude Desktop mostra os detalhes da extensão e cinco configurações; mantenha os padrões e clique em Instalar.
3. No Resolve, abra um projeto e clique em Workspace > Scripts > resolve_mcp_bridge. Esse script é a ponte; a extensão o colocou lá quando iniciou pela primeira vez.
   • A ponte para quando o Resolve é fechado. Clique novamente após cada início do Resolve, antes de usar as ferramentas.
4. Pergunte ao Claude "Você está conectado ao DaVinci Resolve?".

Pelo terminal, qualquer um dos comandos baixa o arquivo e abre a mesma caixa de diálogo.

macOS:

curl -fsSLo ~/Downloads/davinci-resolve-lua-mcp.mcpb https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest/download/davinci-resolve-lua-mcp.mcpb && open ~/Downloads/davinci-resolve-lua-mcp.mcpb

Windows (PowerShell):

Invoke-WebRequest -Uri https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest/download/davinci-resolve-lua-mcp.mcpb -OutFile "$env:USERPROFILE\Downloads\davinci-resolve-lua-mcp.mcpb"; Start-Process "$env:USERPROFILE\Downloads\davinci-resolve-lua-mcp.mcpb"

Se nada abrir, instale o arquivo pelo Claude Desktop: Configurações > Extensões > Configurações avançadas > Instalar extensão.

Para atualizar, baixe o novo arquivo e abra-o; extensões instaladas de um arquivo não se atualizam sozinhas. O servidor atualiza seus dois scripts Lua no próximo início, então clique em Workspace > Scripts > resolve_mcp_bridge novamente depois. Para compilar o pacote você mesmo, veja Desenvolvimento.

Iniciar e parar a ponte

Abra um projeto no Resolve e clique em Workspace > Scripts > resolve_mcp_bridge. Nada aparece no Console (a edição gratuita silencia o print em scripts de menu); a ponte faz loop em segundo plano e o Resolve continua responsivo. No Claude Desktop, resolve_status então relata alive: true com produto, versão, edição, página e projeto aberto.

[!IMPORTANT] A ponte vive e morre com o Resolve. Após cada início do Resolve, clique em Workspace > Scripts > resolve_mcp_bridge novamente antes de usar as ferramentas. Ela nunca é iniciada automaticamente, por design: um loop iniciado por fusion:Execute segura o executor de script compartilhado do Fusion por toda a sessão, então o menu Scripts é o único início suportado.

Para pará-la, peça ao Claude para parar a ponte (stop_bridge), ou feche o Resolve. Clicar no script uma segunda vez enquanto a ponte está ativa é inofensivo: o novo assume e o antigo sai na primeira requisição endereçada à sessão mais nova.

Exemplos de prompts

Give me an overview of the open Resolve project.
List the clips in the root bin with their durations and frame rates.
What is on video track 1 of the current timeline?
Add a blue marker at frame 240 named "fix colour".
Delete all the red markers on this timeline.
Render the current timeline to ~/Movies/out as fix-v2 and tell me when it finishes.
Look up AppendToTimeline in the Resolve scripting docs.
Use run_lua to return the current timeline's start timecode and its item count on V1.

https://github.com/user-attachments/assets/febdf2b9-8e0d-4fbf-8462-0d6ecd98c829

Ferramentas

Cada ferramenta declara suas dicas de acesso ao cliente. delete_markers recusa sem confirm: true, e o Claude é instruído a pedir sua confirmação primeiro; run_lua não exige confirmação e é sinalizada como destrutiva para o cliente poder avisar. Os resultados são JSON com um structuredContent correspondente; as ferramentas paginadas (list_media_pool_clips, get_timeline_items) relatam total, offset, limit e truncated, e cada falha nomeia o próximo passo em vez de lançar erro.

Cores de marcadores: Azul, Ciano, Verde, Amarelo, Vermelho, Rosa, Roxo, Fúcsia, Rosa-claro, Lavanda, Céu, Menta, Limão, Areia, Cacau, Creme.

local project = resolve:GetProjectManager():GetCurrentProject()
local timeline = project:GetCurrentTimeline()
local items = timeline:GetItemListInTrack("video", 1)
local out = {}
for i = 1, #items do
  out[i] = { name = items[i]:GetName(), first = items[i]:GetStart(), last = items[i]:GetEnd() }
end
return { timeline = timeline:GetName(), start_timecode = timeline:GetStartTimecode(), items = out }

[!WARNING] A ponte lida com uma requisição por vez e não consegue responder a diálogos modais do Resolve. Chamadas síncronas longas de API (RenderWithQuickExport, TranscribeAudio, Export, ArchiveProject, LoadProject em um projeto não salvo quando o salvamento automático está desligado) a bloqueiam até terminarem. Inicie renderizações com render_current_timeline e verifique get_render_status em vez de esperar dentro de run_lua.

Configurações

O Claude Desktop mostra estas cinco configurações quando você instala a extensão. Mantenha os padrões para uma instalação padrão do Resolve. Um campo de pasta vazio significa o padrão da plataforma da tabela Caminhos.

Caminhos

Solução de problemas

• A ponte não aparece em Workspace > Scripts. Peça ao Claude por resolve_status e leia bridge_script.outcome:
  • installed, updated ou up_to_date: o arquivo está na pasta de scripts. Reabra o menu; o Resolve lista um arquivo novo sem reiniciar.
  • skipped_auto_install_off: a configuração está desligada. Copie bridge/resolve_mcp_bridge.lua e scripts/claude_diag.lua você mesmo para lá.
  • scripts_dir_missing: a pasta não existe. Abra o Resolve uma vez para que ele a crie, ou corrija a configuração da pasta de scripts; o servidor nunca cria pastas do Resolve.
  • permission_denied ou error: a mensagem do sistema operacional diz o motivo.
• config_problems nomeia o diretório de estado. O caminho não pode ser embutido na ponte: ele contém ]==], uma aspa dupla ou uma quebra de linha, começa com @@, ou contém uma barra invertida no macOS (o Windows reescreve barras invertidas como barras normais). A auto-instalação fica desligada até você mudar a configuração do diretório de estado.
• Copiei o script para Scripts/Deliver. O Resolve também oferece os scripts dessa pasta como scripts de início/fim de renderização selecionáveis na página Deliver, o que não é onde a ponte pertence. Apague a cópia e mantenha o script apenas em Scripts/Utility.
• Fusion.prefs não está atualizando. A ponte grava preferências apenas quando responde a uma solicitação, então primeiro verifique se ela está em execução (resolve_status). O Fusion.prefs mais recente sob a pasta de prefs é o que é lido, seja qual for o nome do perfil; defina a configuração da pasta de prefs somente se essa pasta estiver em outro lugar. Uma gravação que falha enquanto o Resolve está escrevendo o arquivo é tentada até cinco vezes, e uma gravação de início que falha é repetida uma vez por segundo até ser concluída.
• resolve_status diz prefs_missing. Não existe Fusion.prefs sob a pasta de prefs do Fusion. Abra o Resolve pelo menos uma vez, ou aponte a configuração da pasta de prefs para a pasta certa. No Windows o padrão é documentado, mas não medido; se o seu Fusion.prefs estiver em outro lugar, por favor relate o caminho como docs/windows.md descreve.
• Uma solicitação está travada, ou uma ferramenta expira. A ponte está ocupada em uma chamada síncrona longa ou em um diálogo modal que ela não pode responder: espere o Resolve terminar e tente novamente. Solicitações com mais de 120 s são recusadas pela ponte e o servidor remove next.lua após um tempo limite, então nada precisa ser limpo manualmente. Para chamadas lentas, aumente o tempo limite padrão (até 300 s) ou passe timeout_s para run_lua.
• resolve_status diz lock_held. Outro servidor segurou o slot de solicitação por mais tempo que o tempo limite: uma segunda entrada do Claude Desktop, make smoke, ou um loop de registro de desenvolvimento. Pare-o, ou mude a configuração do diretório de estado. Remova o arquivo lock no diretório de estado manualmente apenas se o pid que ele nomeia não for um servidor.
• No Windows, uma ferramenta responde com EBUSY ou EPERM em next.lua. O Windows se recusa a excluir ou substituir um arquivo que outro processo mantém aberto, e a ponte relê o arquivo de solicitação a cada 50 ms, então o servidor tenta novamente por cerca de um segundo. Um erro persistente significa que outra coisa mantém o arquivo aberto, geralmente um antivírus: exclua o diretório de estado da verificação em tempo real.
• No Windows, resolve_status diz state_dir_ascii: false. O Lua do Resolve pode não abrir um caminho com caracteres não ASCII, e toda solicitação então expiraria. Defina o diretório de estado para um caminho apenas ASCII, como C:\rlb.
• O Resolve foi reiniciado no meio da sessão. resolve_status diz resolve_gone (o pid registrado está morto) ou no_reply. O registro da sessão sobrevive ao reinício de propósito, e não há batimento cardíaco, então nada reinicia a ponte por você: clique em Workspace > Scripts > resolve_mcp_bridge novamente.
• A resposta diz truncated: true. O JSON excedeu o limite (64 KB por padrão). Para run_lua, result_preview guarda o início dele; uma ferramenta feita para o limite responde com um erro que nomeia o limite e pede um limit menor ou um offset diferente. Use offset e limit nas ferramentas de lista, ou retorne menos do seu Lua.
• Reinstalar não mostra diálogo. Remova a extensão em Configurações > Extensões, então abra o .mcpb novamente; o Claude Desktop relança o servidor imediatamente.
• Uma ferramenta responde bad_response. O script instalado e o servidor discordam sobre o protocolo, geralmente após uma atualização de um mas não do outro. Reinicie o Claude Desktop para que o servidor reinstale o script, então relance-o pelo menu Scripts.
• Onde estão os logs. O log do próprio servidor é server.log no diretório de estado (truncado em 5 MB; o caminho também está em resolve_status). O Claude Desktop mantém o stderr do servidor como mcp-server-DaVinci Resolve Lua MCP.log na pasta de logs, que registra a conexão, não as chamadas de ferramenta do chat; a extensão instalada é local.mcpb.saad-khan.davinci-resolve-lua-mcp na pasta de extensões (ambos em Paths).

PREFS=~/Library/Application\ Support/Blackmagic\ Design/DaVinci\ Resolve/Fusion/Profiles/Default/Fusion.prefs
grep -o 'RLBResp = "[^"]*"' "$PREFS" | cut -d: -f2 | tr -d '"' | xxd -r -p

$prefs = Join-Path $env:APPDATA 'Blackmagic Design\DaVinci Resolve\Support\Fusion\Profiles\Default\Fusion.prefs'
$hex = ([regex]::Match((Get-Content -Raw -LiteralPath $prefs), 'RLBResp = "([^"]*)"').Groups[1].Value -split ':')[1]
$bytes = [byte[]]::new($hex.Length / 2); for ($i = 0; $i -lt $bytes.Length; $i++) { $bytes[$i] = [Convert]::ToByte($hex.Substring(2 * $i, 2), 16) }
[Text.Encoding]::UTF8.GetString($bytes)

Segurança

[!WARNING] Qualquer coisa que possa gravar um arquivo nesta máquina pode executar Lua dentro do Resolve com seus privilégios. Leia um trecho de run_lua antes de aprová-lo.

• O diretório de estado é esse limite. O macOS o cria com modo 0700; o Windows dá a ele as permissões da pasta do seu perfil (o servidor não define nenhuma própria).
• A última resposta persiste codificada em hexadecimal em Fusion.prefs até a próxima sobrescrevê-la. No Mac medido, esse arquivo tem modo 0666, então qualquer conta local pode ler a resposta anterior; no Windows ele fica sob %APPDATA%, privado para sua conta por padrão (não medido). Uma parada limpa marca o registro da sessão stopped e substitui a última resposta pelo reconhecimento de parada.
• A extensão roda com os privilégios do seu usuário, dentro do modelo de processo do Claude Desktop, sem sandbox próprio. Ela grava apenas seu diretório de estado e os dois arquivos Lua na pasta de scripts do usuário do Resolve.
• Sem rede: o servidor não abre sockets e não faz solicitações. Arquivos entram, preferências saem.

Política de Privacidade

A extensão roda inteiramente na sua máquina e não envia nada para lugar nenhum. A política completa está em PRIVACY.md; em resumo:

• Coleta. Ela processa o que o Claude envia (código Lua, texto de marcadores, nomes, caminhos) e o que o Resolve responde (metadados de projeto, linha do tempo, clipe e marcador, caminhos de mídia). Sem contas, sem credenciais, sem telemetria, análise ou relatórios de falha.
• Uso e armazenamento. Esses dados vivem apenas no arquivo de solicitação (uma chamada, depois excluído), na última resposta em Fusion.prefs, no log do servidor (ids, tempos, caminhos e mensagens de erro; nunca código Lua, argumentos ou resultados) e na cópia desse log no Claude Desktop.
• Compartilhamento com terceiros. Nenhum pela extensão. O Claude Desktop envia entradas e resultados de ferramentas para a Anthropic como parte da sua conversa, sob a política de privacidade da Anthropic; o GitHub serve o download.
• Retenção. Até a próxima chamada ou inicialização da ponte sobrescrever a resposta, até o log passar de 5 MB, e de outra forma até você excluir os arquivos como descrito em Uninstall.
• Contato. Perguntas: abra um issue. Problemas de segurança: a aba Segurança do repositório, como SECURITY.md descreve.

Desinstalação

1. Remova "DaVinci Resolve Lua MCP" em Configurações > Extensões no Claude Desktop.
2. Exclua resolve_mcp_bridge.lua e claude_diag.lua da pasta de scripts (veja Paths); de um checkout no Mac, make uninstall-bridge remove exatamente esses dois arquivos.
3. Exclua o diretório de estado.

As chaves Global.ResolveLuaBridge.* permanecem em Fusion.prefs (menos de 2 KB após uma parada limpa: o registro da sessão, a resposta de parada e oito chaves apagadas). Remova-as das preferências do Fusion se quiser o arquivo impecável.

Desenvolvimento

Pré-requisitos:

• Node 20 ou mais novo e npm (o Makefile usa ~/.nvm/nvm.sh).
• Uma instalação do DaVinci Resolve: os testes Lua rodam sob seu fuscript incluído em /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fuscript.
• Opcionalmente lua-language-server, para make lint-lua.
• O Makefile é apenas para macOS. No Windows, rode os mesmos portões do Git Bash como docs/windows.md lista; os testes fuscript e make smoke não têm equivalente no Windows.

git clone https://github.com/saadk408/davinci-resolve-lua-mcp.git
cd davinci-resolve-lua-mcp
npm install
make test      # Lua checks under fuscript + the Node suite
make bundle    # dist/davinci-resolve-lua-mcp.mcpb, validated and probed
make install   # make bundle, then open the .mcpb so Claude Desktop shows its dialog

O loop de desenvolvimento: make dev-register uma vez, depois make build e reinicie o Claude Desktop após cada mudança, sem reempacotar. A entrada de desenvolvimento e a extensão instalada podem rodar lado a lado: o bloqueio do slot de requisição é tomado por requisição e liberado imediatamente, então um servidor ocioso nunca bloqueia o outro. Eles respondem aos mesmos nomes de ferramentas, então desative um no Claude Desktop enquanto testa o outro. CONTRIBUTING.md tem o fluxo de branch e release.

Releases: enviar uma tag vX.Y.Z executa .github/workflows/release.yml, que roda os gates Node e make bundle no commit marcado, atesta a proveniência do build do bundle, depois publica um GitHub Release imutável com o bundle anexado e seu SHA-256 nas notas; a mensagem de uma tag anotada se torna a introdução das notas. Um segundo job publica o release no MCP Registry como io.github.saadk408/davinci-resolve-lua-mcp, com o hash do arquivo que o release serve. Verifique um bundle baixado com gh attestation verify davinci-resolve-lua-mcp.mcpb -R saadk408/davinci-resolve-lua-mcp. O workflow de testes também roda os gates Node e o gate do bundle em um runner Windows.

[!NOTE] make smoke cria e exclui uma timeline chamada bridge-smoke, adiciona e exclui marcadores nela e define o diretório de destino do render e o nome do arquivo do projeto. SMOKE_PROJECT deve ser o nome do projeto que está aberto no Resolve, e deve ser um projeto de rascunho, nunca uma edição real. A execução se recusa a prosseguir quando os nomes diferem.

Layout:

• bridge/resolve_mcp_bridge.lua: o loop dentro do Resolve, um arquivo sem dependências com menos de 600 linhas.
• src/: o servidor TypeScript. server.ts contém as 15 ferramentas, lua.ts cada snippet Lua e o único helper de escape de strings, protocol.ts o slot de requisição e o bloqueio, prefs.ts o leitor Fusion.prefs, bridgeInstall.ts a auto-instalação.
• scripts/claude_diag.lua: o diagnóstico de sandbox, também enviado no bundle.
• tests/: a suíte Node; tests/lua/: as verificações fuscript.
• docs/: a lista de verificação de medição no Windows (windows.md) e as capturas de tela do README (images/).

Agradecimentos

Este projeto se baseia no trabalho de:

• AutoSubs - ponte Lua sobre preferências do Fusion no 21.1 gratuito, o canal que este projeto adotou
• samuelgursky/davinci-resolve-mcp - servidor MCP para DaVinci Resolve Studio através da API de script Python

DaVinci Resolve é uma marca registrada da Blackmagic Design Pty Ltd. Este projeto não é afiliado ou endossado pela Blackmagic Design.