DaVinci Resolve Lua MCP

Control the free edition of DaVinci Resolve 21.1 from Claude through a Lua script that runs inside Resolve. macOS and Windows (experimental), no Studio licence, no network.

DaVinci Resolve 21.1 moved Python scripting and the external scripting API to the Studio edition, and Blackmagic's own MCP server ships with Studio only. One door is still open on the free edition: Workspace > Scripts lists and runs Lua files. This project puts a small Lua script there. Launched once per Resolve session, it holds the live resolve object and executes Lua on behalf of an MCP server that Claude Desktop runs as an extension.

Features

• 15 purpose-built tools: project overview, project and timeline lists, Media Pool clips, timeline items, markers, timeline and project switching, rendering with status polling, and a search over Blackmagic's shipped scripting reference.

• run_lua for everything else: any Lua 5.1 chunk runs inside Resolve with the live resolve object and returns JSON, captured print output and errors.

• One .mcpb bundle: install it in Claude Desktop, and the server copies its two Lua scripts into Resolve's user scripts folder on first launch.

• No network: the server and the script talk through a request file and Fusion's preferences. There are no sockets, no listeners and no telemetry.

• Fast enough to feel interactive: about 60 ms per call, measured end to end on a Mac.

Related MCP server: DaVinci Resolve MCP Server

Requirements

• macOS (Apple Silicon is the only hardware measured).

• Windows 10 or 11, experimental. The default paths come from Blackmagic's documentation and forum reports; nothing has been measured on Windows yet. docs/windows.md lists what to check.

• DaVinci Resolve 21.1 free edition (build 21.1.0.17 is the one measured). Studio is not needed and not targeted. Blackmagic documents neither this Lua host nor its sandbox, so a point release can change what works.

• Claude Desktop. It ships the Node runtime the server needs (Node 20 or newer); nothing else is installed.

• A project open in Resolve while you use the tools.

Install

1. Download davinci-resolve-lua-mcp.mcpb (the latest release; the release notes and the SHA-256 are on the Releases page).

2. Double-click the file, or drag it onto the Claude Desktop window. Claude Desktop shows the extension's details and five settings; keep the defaults and click Install.

3. In Resolve, open a project and click Workspace > Scripts > resolve_mcp_bridge. That script is the bridge; the extension put it there when it first started.

   • The bridge stops when Resolve quits. Click it again after every Resolve launch, before using the tools.

4. Ask Claude "Are you connected to DaVinci Resolve?".

From a terminal, either command downloads the file and opens the same dialog.

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"

If nothing opens, install the file from Claude Desktop: Settings > Extensions > Advanced settings > Install Extension.

To update, download the new file and open it; extensions installed from a file do not update on their own. The server refreshes its two Lua scripts on its next start, so click Workspace > Scripts > resolve_mcp_bridge again afterwards. To build the bundle yourself, see Development.

Start and stop the bridge

Open a project in Resolve and click Workspace > Scripts > resolve_mcp_bridge. Nothing appears in the Console (the free edition mutes print in menu scripts); the bridge loops in the background and Resolve stays responsive. In Claude Desktop, resolve_status then reports alive: true with the product, version, edition, page and open project.

To stop it, ask Claude to stop the bridge (stop_bridge), or quit Resolve. Clicking the script a second time while the bridge is running is harmless: the new one takes over and the old one exits on the first request addressed to the newer session.

Example 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

Tools

Every tool declares its access hints to the client. delete_markers refuses without confirm: true, and Claude is told to ask you first; run_lua takes no confirmation and is flagged destructive so the client can warn. Results are JSON with a matching structuredContent; the paginated tools (list_media_pool_clips, get_timeline_items) report total, offset, limit and truncated, and every failure names the next step instead of throwing.

Marker colours: Blue, Cyan, Green, Yellow, Red, Pink, Purple, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa, Cream.

The chunk runs inside Resolve's Scripts-menu Lua state (LuaJIT, Lua 5.1) with the globals resolve and fusion. Conventions, as the server also tells Claude:

• Call methods with a colon (project:GetName()) and read constants with a dot (resolve.EXPORT_AAF).

• API lists are 1-based tables: use #list and for i = 1, #list, never pairs. Dicts are keyed tables; GetMarkers() is keyed by frame number.

• Page names for OpenPage are lowercase ("edit", "color", "deliver").

• return a value to get it back as JSON. Only the first return value is sent. print output is invisible in Resolve but comes back in prints (capped at 200 lines / 16 KB).

• Look the method up with scripting_api_docs first, and avoid the deprecated forms Blackmagic's shipped examples still use: GetSetting/SetSetting (use GetSettings()/SetSettings({})), GetItemsInTrack (use GetItemListInTrack), index-based render-job calls (ids are strings) and single-argument GetClipProperty.

• io, os.execute, os.remove, require, package, ffi and debug do not exist in this state; errors carry the message only, without a traceback.

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 }

Settings

Claude Desktop shows these five settings when you install the extension. Keep the defaults for a standard Resolve installation. An empty folder field means the platform default from the Paths table.

Paths

The Windows paths are documented, not measured; the Fusion prefs folder is the least certain of them. A Microsoft Store install of Claude Desktop keeps its folders under %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\ instead.

The settings map onto RLB_SCRIPTS_DIR, RLB_AUTO_INSTALL, RLB_STATE_DIR, RLB_DEFAULT_TIMEOUT_S and RLB_PREFS_DIR; the rest have no setting. A bad value falls back to its default and shows up in resolve_status under config_problems; the server never refuses to start over configuration.

Troubleshooting

• The bridge is missing from Workspace > Scripts. Ask Claude for resolve_status and read bridge_script.outcome:

  • installed, updated or up_to_date: the file is in the scripts folder. Reopen the menu; Resolve lists a new file without a restart.

  • skipped_auto_install_off: the setting is off. Copy bridge/resolve_mcp_bridge.lua and scripts/claude_diag.lua there yourself.

  • scripts_dir_missing: the folder does not exist. Launch Resolve once so it creates it, or fix the scripts-folder setting; the server never creates Resolve folders.

  • permission_denied or error: the operating-system message says why.

• config_problems names the state directory. The path cannot be embedded in the bridge: it contains ]==], a double quote or a newline, starts with @@, or contains a backslash on macOS (Windows rewrites backslashes as forward slashes). Auto-install stays off until you change the State directory setting.

• I copied the script into Scripts/Deliver. Resolve also offers that folder's scripts as selectable render start/end scripts in the Deliver page, which is not where the bridge belongs. Delete the copy and keep the script in Scripts/Utility only.

• Fusion.prefs is not updating. The bridge writes preferences only when it answers a request, so first check that it is running (resolve_status). The newest Fusion.prefs under the prefs folder is the one read, whatever the profile is called; set the prefs-folder setting only if that folder is somewhere else. A save that fails while Resolve is writing the file is attempted up to five times, and a failed start save is retried once a second until it lands.

• resolve_status says prefs_missing. No Fusion.prefs exists under the Fusion prefs folder. Launch Resolve at least once, or point the prefs-folder setting at the right folder. On Windows the default is documented but unmeasured; if your Fusion.prefs lives elsewhere, please report the path as docs/windows.md describes.

• A request is stuck, or a tool times out. The bridge is busy on a long synchronous call or a modal dialog it cannot answer: wait for Resolve to finish, then retry. Requests older than 120 s are refused by the bridge and the server removes next.lua after a timeout, so nothing needs clearing by hand. For slow calls, raise the default timeout (up to 300 s) or pass timeout_s to run_lua.

• resolve_status says lock_held. Another server kept the request slot for longer than the timeout: a second Claude Desktop entry, make smoke, or a dev-register loop. Stop it, or change the State directory setting. Remove the lock file in the state directory by hand only if the pid it names is not a server.

• On Windows, a tool answers with EBUSY or EPERM on next.lua. Windows refuses to delete or replace a file another process holds open, and the bridge re-reads the request file every 50 ms, so the server retries for about a second. A persistent error means something else keeps the file open, usually an antivirus scanner: exclude the state directory from real-time scanning.

• On Windows, resolve_status says state_dir_ascii: false. Resolve's Lua may not open a path with non-ASCII characters, and every request would then time out. Set the state directory to an ASCII-only path such as C:\rlb.

• Resolve was restarted mid-session. resolve_status says resolve_gone (the recorded pid is dead) or no_reply. The session record survives the restart on purpose, and there is no heartbeat, so nothing restarts the bridge for you: click Workspace > Scripts > resolve_mcp_bridge again.

• The response says truncated: true. The JSON exceeded the cap (64 KB by default). For run_lua, result_preview holds the start of it; a purpose-built tool over the cap answers with an error that names the cap and asks for a smaller limit or a different offset. Use offset and limit on the list tools, or return less from your Lua.

• Reinstalling shows no dialog. Remove the extension under Settings > Extensions, then open the .mcpb again; Claude Desktop relaunches the server at once.

• A tool answers bad_response. The installed script and the server disagree on the protocol, usually after an upgrade of one but not the other. Restart Claude Desktop so the server reinstalls the script, then relaunch it from the Scripts menu.

• Where the logs are. The server's own log is server.log in the state directory (truncated at 5 MB; the path is also in resolve_status). Claude Desktop keeps the server's stderr as mcp-server-DaVinci Resolve Lua MCP.log in its logs folder, which records the connection, not the chat's tool calls; the installed extension is local.mcpb.saad-khan.davinci-resolve-lua-mcp in its extensions folder (both in Paths).

The last answer is in Fusion.prefs, hex-encoded. On macOS:

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

On Windows (PowerShell):

$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)

Security

• The state directory is that boundary. macOS creates it with mode 0700; Windows gives it your profile folder's permissions (the server sets none of its own).

• The last response persists hex-encoded in Fusion.prefs until the next one overwrites it. On the measured Mac that file has mode 0666, so any local account can read the previous answer; on Windows it sits under %APPDATA%, private to your account by default (unmeasured). A clean stop marks the session record stopped and replaces the last answer with the stop acknowledgement.

• The extension runs with your user's privileges, inside Claude Desktop's process model, with no sandbox of its own. It writes only its state directory and the two Lua files in Resolve's user scripts folder.

• No network: the server opens no sockets and makes no requests. Files in, preferences out.

Privacy Policy

The extension runs entirely on your machine and sends nothing anywhere. The full policy is PRIVACY.md; in short:

• Collection. It processes what Claude sends it (Lua code, marker text, names, paths) and what Resolve answers (project, timeline, clip and marker metadata, media paths). No accounts, no credentials, no telemetry, analytics or crash reporting.

• Use and storage. That data lives only in the request file (one call, then deleted), the last answer in Fusion.prefs, the server log (ids, timings, paths and error messages; never Lua code, arguments or results) and Claude Desktop's copy of that log.

• Third-party sharing. None by the extension. Claude Desktop sends tool inputs and results to Anthropic as part of your conversation, under Anthropic's privacy policy; GitHub serves the download.

• Retention. Until the next call or bridge launch overwrites the answer, until the log passes 5 MB, and otherwise until you delete the files as described under Uninstall.

• Contact. Questions: open an issue. Security problems: the repository's Security tab, as SECURITY.md describes.

Uninstall

1. Remove "DaVinci Resolve Lua MCP" under Settings > Extensions in Claude Desktop.

2. Delete resolve_mcp_bridge.lua and claude_diag.lua from the scripts folder (see Paths); from a checkout on a Mac, make uninstall-bridge removes exactly those two files.

3. Delete the state directory.

The Global.ResolveLuaBridge.* keys stay in Fusion.prefs (under 2 KB after a clean stop: the session record, the stop answer and eight blanked keys). Remove them from Fusion's preferences if you want the file pristine.

Development

Prerequisites:

• Node 20 or newer and npm (the Makefile sources ~/.nvm/nvm.sh).

• A DaVinci Resolve installation: the Lua tests run under its bundled fuscript at /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fuscript.

• Optionally lua-language-server, for make lint-lua.

• The Makefile is macOS-only. On Windows, run the same gates from Git Bash as docs/windows.md lists; the fuscript tests and make smoke have no Windows equivalent.

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

The developer loop: make dev-register once, then make build and restart Claude Desktop after each change, with no repack. The dev entry and the installed extension can run side by side: the request-slot lock is taken per request and released at once, so an idle server never blocks the other. They answer to the same tool names, though, so disable one in Claude Desktop while testing the other. CONTRIBUTING.md has the branch and release flow.

Releases: pushing a vX.Y.Z tag runs .github/workflows/release.yml, which runs the Node gates and make bundle on the tagged commit, attests the bundle's build provenance, then publishes an immutable GitHub Release with the bundle attached and its SHA-256 in the notes; an annotated tag's message becomes the notes' introduction. A second job publishes the release to the MCP Registry as io.github.saadk408/davinci-resolve-lua-mcp, with the hash of the file the release serves. Verify a downloaded bundle with gh attestation verify davinci-resolve-lua-mcp.mcpb -R saadk408/davinci-resolve-lua-mcp. The tests workflow also runs the Node gates and the bundle gate on a Windows runner.

Layout:

• bridge/resolve_mcp_bridge.lua: the in-Resolve loop, one dependency-free file under 600 lines.

• src/: the TypeScript server. server.ts holds the 15 tools, lua.ts every Lua snippet and the one string-escaping helper, protocol.ts the request slot and lock, prefs.ts the Fusion.prefs reader, bridgeInstall.ts the self-install.

• scripts/claude_diag.lua: the sandbox diagnostic, also shipped in the bundle.

• tests/: the Node suite; tests/lua/: the fuscript checks.

• docs/: the Windows measurement checklist (windows.md) and the README's screenshots (images/).

Acknowledgments

This project builds on the work of:

• AutoSubs - Lua bridge over Fusion preferences on free 21.1, the channel this project adopted

• samuelgursky/davinci-resolve-mcp - MCP server for DaVinci Resolve Studio through the Python scripting API

DaVinci Resolve is a trademark of Blackmagic Design Pty Ltd. This project is not affiliated with or endorsed by Blackmagic Design.