DaVinci Resolve MCP

DaVinci Resolve MCP Server

Inglês | 简体中文

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA controlem o DaVinci Resolve Studio por meio da API oficial de Scripting. Ele fornece cobertura completa da API, além de auxiliares de fluxo de trabalho protegidos para edição, organização do pool de mídia, configuração de renderização, marcadores de revisão, correção de cor, Fusion, Fairlight, tarefas de ciclo de vida do projeto, criação de extensões e análise de mídia segura para a fonte.

Um painel de controle local no navegador acompanha o servidor para inspecionar o estado do Resolve, executar análise segura para a fonte, aprofundar-se em clipes e planos analisados e editar a saída da análise inline. Consulte o Guia do Painel de Controle para o tour completo.

Início Rápido

npx davinci-resolve-mcp setup

Antes de conectar, abra o DaVinci Resolve Studio e defina Preferências > Geral > Uso de script externo para Local. (Na edição gratuita, essa preferência não ajuda — veja Edição gratuita abaixo.) O lançador npm instala uma cópia gerenciada no diretório de dados de aplicativo do usuário e, em seguida, executa o instalador universal do Python. O instalador cria um ambiente virtual, detecta os caminhos do Resolve e pode configurar Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode e IDEs JetBrains.

git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
cd davinci-resolve-mcp
python install.py

Para caminhos de plataforma, configuração específica do cliente e instalação manual, consulte Instalação e Configuração.

O instalador e o servidor verificam a versão mais recente do GitHub para atualizações do MCP. As verificações são de melhor esforço e limitadas; o servidor nunca bloqueia a inicialização do MCP para um prompt. O instalador pode solicitar, adiar, ignorar uma versão, desativar verificações ou aplicar uma atualização automática segura opcional para checkouts git limpos.

Edição gratuita (ponte no aplicativo)

A Blackmagic restringe o script externo ao Studio: na edição gratuita, scriptapp("Resolve") recusa um processo estrangeiro, independentemente do que a preferência diz. O menu Workspace ▸ Scripts não é restrito — um script iniciado a partir dele recebe o objeto resolve ativo em qualquer edição — então o servidor pode alcançar a edição gratuita por meio de um pequeno script que é executado dentro do Resolve e o reexporta por meio de um listener de loopback autenticado.

python scripts/install_resolve_bridge.py
# restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge

Quando esse listener está em execução, ele é usado automaticamente sempre que o script externo não está disponível — nenhuma variável de ambiente é necessária. Definir DAVINCI_RESOLVE_BRIDGE=1 força a ponte: ela se torna o único transporte tentado, então uma ponte que para de responder relata sua própria falha em vez de silenciosamente voltar para outro transporte. Use-a quando a ponte for o caminho que você pretende usar.

No macOS, o Resolve procura o Python 3 em exatamente dois lugares: a variável de ambiente PYTHON3HOME e depois /usr/local/bin/python3. Homebrew, pyenv, uv e conda não estão em nenhum deles, então o script silenciosamente nunca aparece no menu. Uma instalação do python.org funciona porque seu instalador cria /usr/local/bin/python3 — mas você não precisa de uma: aponte o Resolve para o interpretador que você já tem, sem sudo necessário.

launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"

Use launchctl setenv, não export — o Resolve é iniciado a partir do Dock e nunca vê o ambiente do seu shell. Reinicie o Resolve depois. Um canário Lua é instalado junto para que você possa distinguir "Python não detectado" de uma pasta errada.

Validado nas versões gratuita 21.0.3.7 e Studio 19.1.3.7, ambas no macOS. Os caminhos do Windows adicionados na v2.70.1 (issue #106) foram lançados sem verificação; relatos nas versões gratuita 21.0.1.11 (issue #109) e gratuita 21.0.3.7 (issue #112) desde então mostraram a ponte instalando, listando e servindo a partir de ambos %PROGRAMDATA% e %APPDATA% no Windows 11, então esses caminhos agora são confirmados em vez de assumidos. O Linux também é confirmado: um relato na versão gratuita 20.3.2.9 (issue #129, Fedora 43) mostra a ponte instalando em ~/.local/share/DaVinciResolve/Fusion/Scripts/Utility, listando contra o Python do sistema — o Linux não tem esse problema de descoberta — e servindo de ponta a ponta. Nenhuma plataforma agora se baseia em suposição: o macOS foi validado diretamente, o Windows e o Linux com base em relatos de usuários.

Observe que a ponte mantém sua porta enquanto estiver servindo. Antes da v2.70.3, uma ponte do Windows poderia sobreviver ao Resolve e bloquear o listener da próxima sessão; se você estiver em uma versão mais antiga e uma ponte parar de responder, verifique se há um fuscript.exe obsoleto ainda segurando a porta.

Este é o caminho documentado no aplicativo, não uma contornação de licença, mas a Blackmagic pode fechá-lo — trate-o como um nível suportado até que não seja mais. Apenas loopback, solicitações assinadas com HMAC, nonces de uso único.

Painel de Controle Local

Inicie o painel de controle local de usuário único a partir da raiz do repositório:

venv/bin/python -m src.control_panel

O comando inicia um servidor localhost e abre o painel de controle no seu navegador. Para que um agente de codificação de IA faça isso, peça: "Abra o painel de controle do Resolve MCP para este repositório." Os agentes devem usar venv/bin/python -m src.control_panel a menos que seu ambiente Python já esteja ativo. Os trabalhos de análise persistidos atualizam o índice de pesquisa local automaticamente após fatias bem-sucedidas; a ação manual Build Index é para reconstruir a partir de relatórios existentes.

Modos do Servidor

Modo	Ponto de entrada	Ferramentas	Melhor para
Composto	src/server.py	34	Modo padrão para a maioria dos assistentes. Operações relacionadas do Resolve são agrupadas atrás de parâmetros de ação para manter o uso de contexto baixo.
Completo / granular	src/server.py --full ou src/resolve_mcp_server.py	353	Usuários avançados que desejam uma ferramenta MCP por método da API do Resolve.

O servidor composto é recomendado, a menos que você precise especificamente da superfície granular de uma ferramenta por método.

Servidor avançado — além da API de script (opcional, Node)

O mesmo pacote inclui um segundo servidor MCP opcional: davinci-resolve-advanced-mcp (bin bin/davinci-resolve-advanced-mcp.mjs). Enquanto o servidor Python controla um Resolve ao vivo por meio da API de script sancionada, o servidor avançado faz o que a API não pode — ele lê e edita arquivos do Resolve (.drp / .drt / .drx) e aplica alterações em nível de banco de dados/XML sem o Resolve em execução, então ele roda na nuvem ou localmente. 18 ferramentas: drp, drt, drx (codec de classificação por clipe mais um catálogo determinístico de classificação/QC offline — correspondência de pele dentro da câmera + entre câmeras (métrica de linha de pele v2) + b-roll + correspondência de balanço de branco com patch neutro, correspondência com referência, saturação/equilíbrio de preto, normalização de contraste, importação ASC CDL, transferência de classificação sem perdas + criação de visual de temporada, anexação de LUT nomeada, leituras de escopo + tags de intenção, verificação de classificação, extração de quadros com referência de exibição, QC legal para transmissão), offline_ref, conform (conformação/relink QC + linhagem com frame-oracle), color_trace (carregar classificações em uma re-conformação), fusion, audio_plan, fairlight (roteamento de barramento), audio, project_read, project_db, pipeline (um pipeline de banco de dados como verdade: compilar especificações de projeto YAML em um banco de dados SQLite canônico e, em seguida, executar etapas com portões, proveniência e detecção de desvio intenção↔real), capabilities, deliverable (QC de entrega / conformidade), media (front-end de mídia / ingestão AE), editorial (integridade editorial / changelist), provenance (proveniência / auditoria / relatório de episódio). Ele também pode ser consumido como uma biblioteca (API de mecanismo importável), não apenas iniciado como um servidor.

As gravações de classificação DRX são calibradas ao vivo contra o Resolve Studio: os parâmetros de classificação usam as unidades do painel na tela do Resolve por padrão (space: 'ui' | 'drx'), e as gravações estruturais (power windows, qualificadores, zonas HDR, curvas HSL, ColorSlice, efeitos de desfoque/tecla/movimento) são verificadas por leitura do painel — status por controle em resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md. Ele também fecha uma lacuna apenas de interface: "Cleanup Node Graph" programático (drx relayout para um clipe, project_db relayout_node_graphs para um projeto inteiro) — layout de nós organizado, conteúdo de classificação preservado byte a byte.

Adicione-o junto ao servidor ao vivo (ambos vêm em um npm install):

{
  "mcpServers": {
    "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
    "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
  }
}

install.py imprime ambas as entradas. O núcleo é puro JS/MIT sem módulos nativos obrigatórios; alguns recursos precisam de ferramentas instaladas pelo usuário (ffmpeg para audio, sharp/better-sqlite3 para alguns caminhos) — chame a ferramenta capabilities para status ao vivo e dicas de instalação.

Bradford Post Assistant — aplicativo gerenciado (beta fechado)

Os mantenedores também desenvolvem o Bradford Post Assistant, um aplicativo de desktop sobre esta base aberta. Enquanto os servidores MCP dão mãos a um agente, o Post Assistant é o copiloto de trabalho ao redor deles — um assistente de IA no dispositivo para pós-produção, onde o material do cliente nunca sai da estação de trabalho:

• Um copiloto de pós-produção — um aplicativo de desktop que fica ao lado do DaVinci Resolve e observa a sessão ao vivo (linha do tempo, classificações e quadros — não apenas chamadas de API), com um assistente de IA embutido e runtime de agente, análise de mídia local (transcrição, análise de quadros, inteligência editorial) e QC de conformação no aplicativo.
• Memória — memória persistente e criptografada do assistente no dispositivo, além de aprendizado entre episódios extraído dos fatos decodificados do seu pipeline (deriva de visual de temporada, prioridades de correção por câmera, bibliotecas de quadros heróis, reutilização de mapa de caminho de conformação), com acúmulo gerenciado para você e um fluxo de trabalho de insights revisados.
• Autocontido por design — o Post Assistant conecta tudo sozinho: este MCP para controle do Resolve, a API Bradford para seus serviços estendidos e sua escolha de provedor de LLM. Nada para configurar manualmente, nenhum cliente separado para gerenciar, e o aplicativo se mantém (e seu MCP incluído) atualizado com atualizações automáticas assinadas.
• Um conjunto de ferramentas profissionais estendido — cirurgia de classificação em projetos ao vivo, mais de 22 famílias de classificação adaptativas, uma biblioteca de looks curada, validação de especificações de entrega, análise de ritmo/limpeza editorial, direção de cor em linguagem natural e criação de composições Fusion — entregue por meio da API Bradford gerenciada.
• Fluxos de trabalho de produção — as ferramentas brutas compostas em fluxos reais e finalizados (turnover → conformação → QC → entrega, manutenção de visual de temporada, relatórios de episódio) com as proteções e aprovações que uma empresa voltada ao cliente espera.

Atualmente está em beta fechado — você pode solicitar acesso em bradfordoperations.com/software/post-assistant. Os servidores de código aberto são completos e totalmente funcionais por conta própria.

O Que Você Pode Fazer

"List all projects and open the one called 'My Film'"
"Create a timeline called 'Assembly Cut' from all clips in the current bin"
"Build a multicam prep timeline from selected camera angles and preserve source media"
"Detect 2-pops or slate claps and suggest record offsets for sync prep"
"Publish analysis summaries, keywords, people, and slate hints into Resolve clip metadata"
"Probe this timeline for gaps, overlaps, missing media, and source frame ranges"
"Safely import this image sequence, organize it into bins, and normalize clip metadata"
"Build a ProRes 422 HQ render plan, validate the settings, and queue the job"
"Copy review markers from the timeline to the selected clip and export a review report"
"Snapshot this clip's grade, validate a CDL update, and export a temp LUT"
"Create a Fusion TextPlus overlay on the selected clip and verify graph connections"
"Report audio channel mappings, voice isolation availability, and subtitle support"
"Install this MCP-marked DCTL or script, classify refresh/restart needs, then remove it"

Recursos Principais

Área	O que o servidor composto suporta
Controle de aplicativo e projeto	Iniciar/reconectar, alternância de páginas, CRUD de projetos, pastas de projetos, bancos de dados, wrappers de projetos na nuvem, configurações, predefinições, arquivos
Media pool e ingestão	Importação segura, sequências de imagens, timelines de preparação multicam, organização de bins, normalização de metadados, inventário de campos de metadados, marcas, anotações, proteções de relink/proxy/resolução completa
Análise de mídia	Análise segura de arquivo/clip/bin/projeto, detecção de eventos de sincronização 2-pop/slate-clap, gravação de metadados padrão do Resolve e marcadores de Media Pool, artefatos de análise persistidos, reutilização de relatórios existentes, análise visual de host_chat_paths (finalizada por clip com commit_vision, funciona com qualquer cliente MCP com capacidade de visão) com opção de desativação, transcrição com opção de desativação
Edição de timeline e conform	Sondagem de trilhas/itens, leituras/gravações de varreduras de chaves de título, helpers de copiar/mover/duplicar, operações de intervalo, lacunas/sobreposições, intervalos de origem, exportações/importações de intercâmbio verificadas
Anotações de revisão	Marcadores de timeline/item/clip, dados personalizados, flags, cor de clip, helpers de copiar/mover/sincronizar/limpar, relatórios de revisão, revisão de miniaturas de marcadores
Cor e finalização	Sondagem de grafo de nós, validação de CDL, cópia de grade, helpers de DRX/LUT, versões, stills da Gallery, grupos de cor
Fusion	Comps de itens de timeline, criação segura de ferramentas, gravações de entrada, inspeção de portas, conexões validadas, gravações em lote com escopo
Áudio e Fairlight	Sondagens de trilha/item, mapeamento de origem, gravações protegidas de propriedades de áudio, isolamento de voz, planejamento de auto-sincronização, sondagens de transcrição/legendas
Render e exportação	Sondagem da matriz de formato/codec, validação de configurações de render, verificações do ciclo de vida de jobs na fila, Quick Export protegida
Autoria de extensões	Helpers de ciclo de vida de scripts Lua/Python de Fuse, DCTL, ACES DCTL e página Resolve, com instalação/remoção segura marcada como MCP

Extras Opcionais

A instalação principal é propositalmente enxuta: Python, ffmpeg e a API de script do Resolve. Alguns recursos precisam de mais, e cada um recusa honestamente com sua própria linha de instalação, em vez de degradar em um palpite — um tempo fabricado ou um nível inventado produz uma saída errada e confiante, o que é pior do que nenhum recurso.

Execute python scripts/doctor.py para ver quais destes você possui.

Extra	Desbloqueia	Licença
ffmpeg no PATH	Detecção de silêncio, marcadores de espaço morto, medição de nível, análise de áudio. A coisa mais útil de instalar.	LGPL/GPL — invocado como subprocesso, nunca empacotado
pip install numpy	Pré-balanceamento de cor, correspondência de stills de referência, auditoria de densidade sonora	BSD
pip install librosa	Detecção de batida, compasso e frase para edição orientada por música	ISC
pip install -U openai-whisper	Transcrição e tudo o que é construído nela em nível de palavra	MIT
pip install open_clip_torch	Similaridade visual e find_similar	MIT
pip install transformers	Embeddings de áudio CLAP	Apache-2.0
pip install opencv-python	Análise adicional de quadros	Apache-2.0

A ação media_analysis capabilities relata a pilha de análise em detalhes e informa o que cada peça ausente habilitaria.

Nada aqui é empacotado. Pesos de modelos têm suas próprias licenças, separadas do código que os carrega; verifique-os antes do uso comercial.

O Que Isto Não Faz

Saber onde uma ferramenta para vale tanto quanto saber o que ela faz, e é mais barato ler isso aqui do que descobrir no meio do projeto.

Não suportado	Porquê, e o que você tem em vez disso
Escolher a melhor take	Performance é a maior parte do que torna uma take correta, e nada disso é mensurável a partir de uma forma de onda ou de uma transcrição. rank_takes classifica fluência — preenchimentos, recomeços, cobertura do roteiro — e diz isso em toda resposta. A take que é usada na edição é frequentemente a menos fluente, porque a hesitação muitas vezes é a atuação. Use para encontrar a take limpa de segurança, não para escolher a leitura.
Cortar no ritmo da música	Ainda não há detecção de batida ou downbeat. Ferramentas orientadas por fala lerão um fundo musical como uma longa região e são o instrumento errado para isso.
Julgar um corte	Nada aqui tem opinião sobre se uma edição é boa. Toda ação destrutiva é plano → revisão → confirmação por esse motivo.
Substituir um editor	A saída é uma montagem de primeira passada, no sentido de assistente de edição: ingestão, sincronização, organização, string out, sinalização de problemas. É um ponto de partida que você corta, não um corte final. Os padrões são deliberadamente generosos — uma primeira montagem deve ficar longa, porque aparar é rápido e visível, enquanto recuperar material descartado é lento e invisível.
Modificar sua mídia de origem	Por design e sem exceção — veja abaixo.

Qualquer coisa analisada, mas não verificável, é relatada como não verificada, nunca convertida em "tudo bem". Um resultado vazio significa "nada encontrado", nunca "nada a encontrar".

Segurança da Mídia de Origem

Este projeto trata originais de câmera e mídia de origem como imutáveis. Ferramentas de análise leem arquivos de origem e gravam relatórios apenas em diretórios sidecar, temporários ou de análise de projeto; a publicação confirmada de metadados grava apenas no banco de dados do projeto do Resolve. O servidor não deve modificar, transcodificar, criar proxies ou derivados da mídia de origem, a menos que o usuário peça explicitamente. Veja o Guia de Análise de Mídia para o fluxo de trabalho detalhado de segurança da origem.

Postura de Segurança

O servidor padrão é um processo stdio local iniciado pelo seu cliente MCP; ele não expõe um listener de rede nem uma superfície de autenticação multiusuário embutida. Os metadados das ferramentas incluem dicas de segurança para clientes MCP para operações somente leitura, destrutivas, idempotentes e de recursos externos. Veja a Política de Segurança para limites operacionais, orientação de confirmação e relato de vulnerabilidades.

Estatísticas-Chave

Métrica	Valor
Ferramentas MCP	34 compostas / 353 granulares (servidor ativo)
Ferramentas avançadas (offline)	18 — autoria de .drp/.drt/.drx + banco de dados, sem Resolve em execução
Ações do Kernel	136 ações de fluxo de trabalho protegidas em 9 ferramentas compostas
Métodos de API Cobertos	361/361 (100%)
Métodos Testados ao Vivo	338/361 (93,6%)
Taxa de Aprovação de Testes ao Vivo	338/338 (100%)
Testado Contra	DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio + Resolve 21.0.3 gratuito (via bridge no aplicativo)

Para o status método a método, veja Cobertura de API e Resultados de Testes. Para o suporte atual de fluxos de trabalho, veja Cobertura de Ações do Kernel.

analyze_media executa diretamente por padrão, persiste relatórios/artefatos inspecionáveis sob a raiz de análise, solicita análise visual do chat do host via protocolo host_chat_paths (analyze retorna caminhos absolutos de quadros + um esquema JSON; o chat do host lê cada quadro como imagem e chama media_analysis(action="commit_vision", ...) para finalizar), executa transcrição através do backend local configurado e grava resumos de análise além de marcadores de clip da Media Pool em tempo de origem de volta ao projeto do Resolve. Passe include_visuals=false, include_transcription=false, publish_metadata=false, timed_markers=no ou dry_run=true apenas quando quiser desativar esses comportamentos padrão. Pular commit_vision deixa a execução em pending_host_vision_analysis — exibida como modo de falha, não rebaixada silenciosamente.

Documentação

Documento	Use para
Instalação e Configuração	Requisitos, opções de instalador, clientes suportados, modos de servidor, configuração manual
Cobertura de API e Resultados de Testes	Estatísticas-chave, tabela de cobertura de API, status de teste ao vivo, referência completa de métodos
Cobertura de Ações do Kernel	Mapa atual de ações de fluxo de trabalho protegidas
Referência de Habilidades de IA	Contexto operacional para assistentes de IA que usam o servidor composto
Guia do Painel de Controle	Tour do painel do navegador local: Visão Geral, Revisão (bin/clip/cena), Análise, Configuração, Preferências
Guia de Análise de Mídia	Fluxos de trabalho seguros de FFprobe, FFmpeg, Whisper, sidecar e raiz de análise
Guia do Helper de Configuração Multicam	Preparação de timeline empilhada, limite do helper/API e etapas de conversão na interface do Resolve
Guia de Decisões Editoriais	Orientação de arte editorial pertencente ao projeto para análises e decisões de timeline
Conformando um AAF Avid	Por que todas as três rotas nativas do Resolve falham em um turnover consolidado e qual delas é perigosa
Guia de Decisões de Cor	Orientação de correção de cor pertencente ao projeto e limites da API de cor do Resolve
Contribuição e Estrutura do Repositório	Fluxo de trabalho de contribuição, suporte de plataformas, notas de segurança, estrutura do repositório
Política de Segurança	Limite de confiança stdio local, metadados de ferramentas, orientação de confirmação, relato
Processo de Release	Checklist de release do mantenedor, superfícies de versão, validação, tags e notas de release
Changelog	Notas de release históricas

Referências de autoria de extensões estão em docs/authoring. Notas de pacotes de desenvolvimento do Resolve estão em docs/notes e docs/integrations. Receitas de prompts estão em examples.

Requisitos

• DaVinci Resolve 18.5+ em macOS, Windows ou Linux. O Studio suporta scripting externo diretamente. A edição gratuita não — a Blackmagic restringe o scripting externo ao Studio — mas ainda é alcançável através do bridge no aplicativo, que roda dentro do Resolve a partir do menu não restrito Workspace ▸ Scripts.
• Python 3.10+ (3.10-3.12 é a faixa de menor risco). Python 3.13/3.14 também funcionam em builds recentes do Resolve (verificado no Studio 20.3.2); builds mais antigos podem falhar ao conectar no 3.13+, caso em que use 3.10-3.12.
• Scripting externo do Resolve configurado como Local (Studio). Na edição gratuita, essa preferência não tem efeito — use o bridge no aplicativo em vez disso.

O Resolve 19.1.3 permanece como linha de base de compatibilidade. Chamadas de scripting do Resolve 20.x são aditivas, protegidas por versão e testadas ao vivo no 20.3.2. Adições de scripting do Resolve 21.0 (classificação de áudio, transcrição com detecção de falante, IntelliSearch, análise de slate, desfoque de movimento, geração de fala, controle de tarefas em segundo plano de sessão) são expostas atrás de detecção de capacidade em tempo de execução, então permanecem inertes em builds mais antigas e ativam automaticamente no Resolve 21+. São testadas ao vivo no Studio 21.0.2.4 — veja o delta do Resolve 21. Observe que AnalyzeForIntellisearch, AnalyzeForSlate e GenerateSpeech exigem cada um um pacote de Extras de IA baixado separadamente, e o Resolve relata um pacote ausente de forma inconsistente (alguns retornam False, outros uma string de erro), então essas ações relatam success: false com o motivo fornecido pelo Resolve, em vez de adivinhar.

Desenvolvimento

python src/server.py          # Compound server
python src/server.py --full   # Granular server
venv/bin/python tests/test_import.py
venv/bin/python scripts/audit_api_parity.py

Regras de release e validação estão em docs/process/release-process.md. Agentes de IA que trabalham neste repositório devem começar com AGENTS.md; usuários do Claude Code também podem ler CLAUDE.md, que aponta para as mesmas instruções canônicas.

Licença

MIT

Autor

Samuel Gursky (samgursky@gmail.com)

• GitHub: github.com/samuelgursky

Agradecimentos

• Blackmagic Design pelo DaVinci Resolve e sua API de scripting
• A equipe do Model Context Protocol por viabilizar a integração com assistentes de IA