DaVinci Resolve Lua MCP

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.

[!NOTE]

Nothing here unlocks Studio features: the bridge uses the free edition's own Lua scripting API. Studio 21.1 users already have Blackmagic's native MCP server.

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.

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.

1. 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.

Scripts menu listing claude_diag and resolve_mcp_bridge">

[!IMPORTANT]

The bridge lives and dies with Resolve. After every Resolve launch, click Workspace > Scripts > resolve_mcp_bridge again before using the tools. It is never started automatically, by design: a loop started through fusion:Execute holds Fusion's shared script executor for the whole session, so the Scripts menu is the only supported launch.

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.

Writing Lua for run_lua

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 }

[!WARNING]

The bridge handles one request at a time and cannot answer Resolve's modal dialogs. Long synchronous API calls (RenderWithQuickExport, TranscribeAudio, Export, ArchiveProject, LoadProject on an unsaved project when live save is off) block it until they finish. Start renders with render_current_timeline and poll