Davinci Resolve Lua MCP

DaVinci Resolve Lua MCP

Controla la edición gratuita de DaVinci Resolve 21.1 desde Claude mediante un script Lua que se ejecuta dentro de Resolve. macOS y Windows (experimental), sin licencia Studio, sin red.

DaVinci Resolve 21.1 movió los scripts de Python y la API de scripting externa a la edición Studio, y el servidor MCP propio de Blackmagic se distribuye solo con Studio. Aún queda una puerta abierta en la edición gratuita: Workspace > Scripts lista y ejecuta archivos Lua. Este proyecto coloca un pequeño script Lua allí. Lanzado una vez por sesión de Resolve, mantiene el objeto resolve en vivo y ejecuta Lua en nombre de un servidor MCP que Claude Desktop ejecuta como extensión.

[!NOTE] Nada de esto desbloquea funciones de Studio: el puente usa la API de scripting Lua propia de la edición gratuita. Los usuarios de Studio 21.1 ya tienen el servidor MCP nativo de Blackmagic.

Características

• 15 herramientas específicas: resumen del proyecto, listas de proyectos y líneas de tiempo, clips del Media Pool, elementos de línea de tiempo, marcadores, cambio de línea de tiempo y proyecto, renderizado con sondeo de estado y una búsqueda en la referencia de scripting incluida por Blackmagic.
• run_lua para todo lo demás: cualquier fragmento de Lua 5.1 se ejecuta dentro de Resolve con el objeto resolve en vivo y devuelve JSON, salida capturada de print y errores.
• Un paquete .mcpb: instálalo en Claude Desktop y el servidor copia sus dos scripts Lua en la carpeta de scripts de usuario de Resolve en el primer inicio.
• Sin red: el servidor y el script se comunican mediante un archivo de solicitud y las preferencias de Fusion. No hay sockets, ni listeners, ni telemetría.
• Suficientemente rápido para sentirse interactivo: aproximadamente 60 ms por llamada, medido de extremo a extremo en un Mac.

Requisitos

• macOS (Apple Silicon es el único hardware medido).
• Windows 10 u 11, experimental. Las rutas predeterminadas provienen de la documentación de Blackmagic y de informes del foro; nada se ha medido en Windows todavía. docs/windows.md enumera qué verificar.
• DaVinci Resolve 21.1 edición gratuita (la compilación 21.1.0.17 es la medida). Studio no es necesario ni está contemplado. Blackmagic no documenta ni este host Lua ni su sandbox, por lo que una versión puntual puede cambiar lo que funciona.
• Claude Desktop. Incluye el runtime de Node que el servidor necesita (Node 20 o superior); no se instala nada más.
• Un proyecto abierto en Resolve mientras usas las herramientas.

Instalación

1. Descarga davinci-resolve-lua-mcp.mcpb (la última versión; las notas de la versión y el SHA-256 están en la página de Releases).
2. Haz doble clic en el archivo, o arrástralo a la ventana de Claude Desktop. Claude Desktop muestra los detalles de la extensión y cinco ajustes; mantén los valores predeterminados y haz clic en Instalar.
3. En Resolve, abre un proyecto y haz clic en Workspace > Scripts > resolve_mcp_bridge. Ese script es el puente; la extensión lo colocó allí cuando se inició por primera vez.
   • El puente se detiene cuando Resolve se cierra. Haz clic de nuevo después de cada inicio de Resolve, antes de usar las herramientas.
4. Pregunta a Claude "¿Estás conectado a DaVinci Resolve?".

Desde una terminal, cualquiera de los dos comandos descarga el archivo y abre el mismo 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"

Si no se abre nada, instala el archivo desde Claude Desktop: Configuración > Extensiones > Configuración avanzada > Instalar extensión.

Para actualizar, descarga el nuevo archivo y ábrelo; las extensiones instaladas desde un archivo no se actualizan solas. El servidor actualiza sus dos scripts Lua en su próximo inicio, así que haz clic en Workspace > Scripts > resolve_mcp_bridge de nuevo después. Para compilar el paquete tú mismo, consulta Desarrollo.

Iniciar y detener el puente

Abre un proyecto en Resolve y haz clic en Workspace > Scripts > resolve_mcp_bridge. No aparece nada en la Consola (la edición gratuita silencia print en los scripts del menú); el puente se ejecuta en segundo plano y Resolve sigue respondiendo. En Claude Desktop, resolve_status luego informa alive: true con el producto, versión, edición, página y proyecto abierto.

[!IMPORTANT] El puente vive y muere con Resolve. Después de cada inicio de Resolve, haz clic en Workspace > Scripts > resolve_mcp_bridge de nuevo antes de usar las herramientas. Nunca se inicia automáticamente, por diseño: un bucle iniciado a través de fusion:Execute mantiene el ejecutor de scripts compartido de Fusion durante toda la sesión, por lo que el menú Scripts es la única forma de inicio compatible.

Para detenerlo, pide a Claude que detenga el puente (stop_bridge), o cierra Resolve. Hacer clic en el script una segunda vez mientras el puente está en ejecución es inofensivo: el nuevo toma el control y el anterior sale en la primera solicitud dirigida a la sesión más nueva.

Ejemplos 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

Herramientas

Cada herramienta declara sus indicaciones de acceso al cliente. delete_markers se niega sin confirm: true, y se le dice a Claude que te pregunte primero; run_lua no requiere confirmación y está marcada como destructiva para que el cliente pueda advertir. Los resultados son JSON con un structuredContent correspondiente; las herramientas paginadas (list_media_pool_clips, get_timeline_items) informan total, offset, limit y truncated, y cada fallo nombra el siguiente paso en lugar de lanzar una excepción.

Colores de marcadores: Azul, Cian, Verde, Amarillo, Rojo, Rosa, Púrpura, Fucsia, Rosa intenso, Lavanda, Cielo, Menta, Limón, Arena, Cacao, Crema.

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] El puente maneja una solicitud a la vez y no puede responder a los diálogos modales de Resolve. Las llamadas síncronas largas a la API (RenderWithQuickExport, TranscribeAudio, Export, ArchiveProject, LoadProject en un proyecto sin guardar cuando el guardado en vivo está desactivado) lo bloquean hasta que terminan. Inicia los renders con render_current_timeline y sondea get_render_status en lugar de esperar dentro de run_lua.

Configuración

Claude Desktop muestra estos cinco ajustes cuando instalas la extensión. Mantén los valores predeterminados para una instalación estándar de Resolve. Un campo de carpeta vacío significa el valor predeterminado de la plataforma de la tabla de Rutas.

Rutas

Solución de problemas

• El puente falta en Workspace > Scripts. Pide a Claude resolve_status y lee bridge_script.outcome:
  • installed, updated o up_to_date: el archivo está en la carpeta de scripts. Vuelve a abrir el menú; Resolve lista un archivo nuevo sin reiniciar.
  • skipped_auto_install_off: el ajuste está desactivado. Copia bridge/resolve_mcp_bridge.lua y scripts/claude_diag.lua allí tú mismo.
  • scripts_dir_missing: la carpeta no existe. Inicia Resolve una vez para que la cree, o corrige el ajuste de la carpeta de scripts; el servidor nunca crea carpetas de Resolve.
  • permission_denied o error: el mensaje del sistema operativo dice por qué.
• config_problems nombra el directorio de estado. La ruta no se puede incrustar en el puente: contiene ]==], una comilla doble o un salto de línea, comienza con @@, o contiene una barra invertida en macOS (Windows reescribe las barras invertidas como barras diagonales). La autoinstalación permanece desactivada hasta que cambies el ajuste del directorio de estado.
• Copié el script en Scripts/Deliver. Resolve también ofrece los scripts de esa carpeta como scripts de inicio/fin de renderizado seleccionables en la página Entregar, que no es donde pertenece el puente. Elimina la copia y mantén el script solo en Scripts/Utility.
• Fusion.prefs no se actualiza. El puente escribe las preferencias solo cuando responde a una solicitud, así que primero verifica que esté ejecutándose (resolve_status). El Fusion.prefs más reciente bajo la carpeta de preferencias es el que se lee, sea cual sea el nombre del perfil; configura el ajuste de la carpeta de preferencias solo si esa carpeta está en otro lugar. Un guardado que falla mientras Resolve escribe el archivo se intenta hasta cinco veces, y un guardado inicial fallido se reintenta una vez por segundo hasta que se completa.
• resolve_status dice prefs_missing. No existe ningún Fusion.prefs bajo la carpeta de preferencias de Fusion. Inicia Resolve al menos una vez, o apunta el ajuste de la carpeta de preferencias a la carpeta correcta. En Windows el valor predeterminado está documentado pero no medido; si tu Fusion.prefs está en otro lugar, informa la ruta como describe docs/windows.md.
• Una solicitud está bloqueada, o una herramienta agota el tiempo. El puente está ocupado en una llamada síncrona larga o en un diálogo modal que no puede responder: espera a que Resolve termine y reintenta. Las solicitudes de más de 120 s son rechazadas por el puente y el servidor elimina next.lua tras un tiempo de espera, así que no hay que limpiar nada a mano. Para llamadas lentas, aumenta el tiempo de espera predeterminado (hasta 300 s) o pasa timeout_s a run_lua.
• resolve_status dice lock_held. Otro servidor mantuvo el espacio de solicitud durante más tiempo que el tiempo de espera: una segunda entrada de Claude Desktop, make smoke, o un bucle de registro de desarrollo. Detenlo, o cambia el ajuste del directorio de estado. Elimina el archivo lock en el directorio de estado a mano solo si el pid que nombra no es un servidor.
• En Windows, una herramienta responde con EBUSY o EPERM en next.lua. Windows se niega a eliminar o reemplazar un archivo que otro proceso mantiene abierto, y el puente relee el archivo de solicitud cada 50 ms, así que el servidor reintenta durante aproximadamente un segundo. Un error persistente significa que algo más mantiene el archivo abierto, generalmente un escáner antivirus: excluye el directorio de estado del escaneo en tiempo real.
• En Windows, resolve_status dice state_dir_ascii: false. El Lua de Resolve puede no abrir una ruta con caracteres no ASCII, y cada solicitud agotaría el tiempo. Configura el directorio de estado a una ruta solo ASCII como C:\rlb.
• Resolve se reinició a mitad de sesión. resolve_status dice resolve_gone (el pid registrado está muerto) o no_reply. El registro de sesión sobrevive al reinicio a propósito, y no hay latido, así que nada reinicia el puente por ti: haz clic en Workspace > Scripts > resolve_mcp_bridge de nuevo.
• La respuesta dice truncated: true. El JSON excedió el límite (64 KB por defecto). Para run_lua, result_preview contiene el inicio; una herramienta diseñada específicamente sobre el límite responde con un error que nombra el límite y pide un limit más pequeño o un offset diferente. Usa offset y limit en las herramientas de lista, o devuelve menos desde tu Lua.
• Reinstalar no muestra ningún diálogo. Elimina la extensión en Configuración > Extensiones, luego abre el .mcpb de nuevo; Claude Desktop relanza el servidor de inmediato.
• Una herramienta responde bad_response. El script instalado y el servidor no coinciden en el protocolo, generalmente después de actualizar uno pero no el otro. Reinicia Claude Desktop para que el servidor reinstale el script, luego relánzalo desde el menú Scripts.
• Dónde están los registros. El registro del servidor es server.log en el directorio de estado (truncado a 5 MB; la ruta también está en resolve_status). Claude Desktop mantiene el stderr del servidor como mcp-server-DaVinci Resolve Lua MCP.log en su carpeta de registros, que registra la conexión, no las llamadas de herramientas del chat; la extensión instalada es local.mcpb.saad-khan.davinci-resolve-lua-mcp en su carpeta de extensiones (ambos en Rutas).

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)

Seguridad

[!WARNING] Cualquier cosa que pueda escribir un archivo en esta máquina puede ejecutar Lua dentro de Resolve con tus privilegios. Lee un fragmento de run_lua antes de aprobarlo.

• El directorio de estado es ese límite. macOS lo crea con modo 0700; Windows le da los permisos de tu carpeta de perfil (el servidor no establece ninguno propio).
• La última respuesta persiste codificada en hexadecimal en Fusion.prefs hasta que la siguiente la sobrescribe. En el Mac medido ese archivo tiene modo 0666, así que cualquier cuenta local puede leer la respuesta anterior; en Windows está bajo %APPDATA%, privado para tu cuenta por defecto (no medido). Una detención limpia marca el registro de sesión stopped y reemplaza la última respuesta con el acuse de detención.
• La extensión se ejecuta con los privilegios de tu usuario, dentro del modelo de procesos de Claude Desktop, sin sandbox propio. Escribe solo su directorio de estado y los dos archivos Lua en la carpeta de scripts de usuario de Resolve.
• Sin red: el servidor no abre sockets y no hace solicitudes. Archivos adentro, preferencias afuera.

Política de privacidad

La extensión se ejecuta completamente en tu máquina y no envía nada a ningún lugar. La política completa está en PRIVACY.md; en resumen:

• Recopilación. Procesa lo que Claude le envía (código Lua, texto de marcadores, nombres, rutas) y lo que Resolve responde (metadatos de proyecto, línea de tiempo, clip y marcador, rutas de medios). Sin cuentas, sin credenciales, sin telemetría, análisis o informes de fallos.
• Uso y almacenamiento. Esos datos viven solo en el archivo de solicitud (una llamada, luego eliminado), la última respuesta en Fusion.prefs, el registro del servidor (ids, tiempos, rutas y mensajes de error; nunca código Lua, argumentos o resultados) y la copia de ese registro en Claude Desktop.
• Compartición con terceros. Ninguna por la extensión. Claude Desktop envía entradas y resultados de herramientas a Anthropic como parte de tu conversación, bajo la política de privacidad de Anthropic; GitHub sirve la descarga.
• Retención. Hasta que la siguiente llamada o el lanzamiento del puente sobrescriba la respuesta, hasta que el registro pase 5 MB, y de otro modo hasta que elimines los archivos como se describe en Desinstalación.
• Contacto. Preguntas: abre un problema. Problemas de seguridad: la pestaña Seguridad del repositorio, como describe SECURITY.md.

Desinstalación

1. Elimina "DaVinci Resolve Lua MCP" en Configuración > Extensiones en Claude Desktop.
2. Elimina resolve_mcp_bridge.lua y claude_diag.lua de la carpeta de scripts (ver Rutas); desde un checkout en un Mac, make uninstall-bridge elimina exactamente esos dos archivos.
3. Elimina el directorio de estado.

Las claves Global.ResolveLuaBridge.* permanecen en Fusion.prefs (menos de 2 KB después de una detención limpia: el registro de sesión, la respuesta de detención y ocho claves en blanco). Elimínalas de las preferencias de Fusion si quieres el archivo prístino.

Desarrollo

Requisitos previos:

• Node 20 o más reciente y npm (el Makefile obtiene ~/.nvm/nvm.sh).
• Una instalación de DaVinci Resolve: las pruebas Lua se ejecutan bajo su fuscript incluido en /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fuscript.
• Opcionalmente lua-language-server, para make lint-lua.
• El Makefile es solo para macOS. En Windows, ejecuta las mismas compuertas desde Git Bash como lista docs/windows.md; las pruebas fuscript y make smoke no tienen equivalente en 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

El bucle de desarrollo: make dev-register una vez, luego make build y reiniciar Claude Desktop después de cada cambio, sin reempaquetar. La entrada de desarrollo y la extensión instalada pueden ejecutarse en paralelo: el bloqueo de ranura de solicitud se toma por solicitud y se libera de inmediato, por lo que un servidor inactivo nunca bloquea al otro. Responden a los mismos nombres de herramientas, sin embargo, así que desactiva uno en Claude Desktop mientras pruebas el otro. CONTRIBUTING.md tiene el flujo de ramas y lanzamientos.

Lanzamientos: empujar una etiqueta vX.Y.Z ejecuta .github/workflows/release.yml, que ejecuta las compuertas de Node y make bundle en el commit etiquetado, atestigua la procedencia de compilación del bundle, luego publica un Release de GitHub inmutable con el bundle adjunto y su SHA-256 en las notas; el mensaje de una etiqueta anotada se convierte en la introducción de las notas. Un segundo trabajo publica el release en el MCP Registry como io.github.saadk408/davinci-resolve-lua-mcp, con el hash del archivo que sirve el release. Verifica un bundle descargado con gh attestation verify davinci-resolve-lua-mcp.mcpb -R saadk408/davinci-resolve-lua-mcp. El flujo de trabajo de pruebas también ejecuta las compuertas de Node y la compuerta del bundle en un runner de Windows.

[!NOTE] make smoke crea y elimina una línea de tiempo llamada bridge-smoke, agrega y elimina marcadores en ella, y establece el directorio de destino del render y el nombre de archivo del proyecto. SMOKE_PROJECT debe ser el nombre del proyecto que está abierto en Resolve, y debería ser un proyecto de prueba, nunca una edición real. La ejecución se niega a continuar cuando los nombres difieren.

Diseño:

• bridge/resolve_mcp_bridge.lua: el bucle dentro de Resolve, un archivo sin dependencias de menos de 600 líneas.
• src/: el servidor TypeScript. server.ts contiene las 15 herramientas, lua.ts cada fragmento de Lua y el único helper de escape de cadenas, protocol.ts la ranura de solicitud y el bloqueo, prefs.ts el lector de Fusion.prefs, bridgeInstall.ts la autoinstalación.
• scripts/claude_diag.lua: el diagnóstico de sandbox, también incluido en el bundle.
• tests/: la suite de Node; tests/lua/: las comprobaciones de fuscript.
• docs/: la lista de verificación de medición en Windows (windows.md) y las capturas de pantalla del README (images/).

Agradecimientos

Este proyecto se basa en el trabajo de:

• AutoSubs - Puente Lua sobre preferencias de Fusion en 21.1 gratuito, el canal que este proyecto adoptó
• samuelgursky/davinci-resolve-mcp - Servidor MCP para DaVinci Resolve Studio a través de la API de scripting de Python

DaVinci Resolve es una marca comercial de Blackmagic Design Pty Ltd. Este proyecto no está afiliado ni respaldado por Blackmagic Design.