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, no Studio licence, no network.*

[![tests](https://github.com/saadk408/davinci-resolve-lua-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/saadk408/davinci-resolve-lua-mcp/actions/workflows/tests.yml) [![Release](https://img.shields.io/github/v/release/saadk408/davinci-resolve-lua-mcp)](https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest) [![License: MIT](https://img.shields.io/github/license/saadk408/davinci-resolve-lua-mcp)](LICENSE) ![macOS](https://img.shields.io/badge/platform-macOS-lightgrey) ![DaVinci Resolve 21.1 free edition](https://img.shields.io/badge/DaVinci_Resolve-21.1_free-blue)

![Claude Desktop describing the open project next to the same project in DaVinci Resolve 21.1 free edition](docs/images/hero-image.png)

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. Requests travel as a file, answers come back through Fusion's preferences file, and nothing leaves the Mac.

> [!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

- **14 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 this Mac.

## Requirements

- macOS. Apple Silicon is the only hardware measured.
- 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`](https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest/download/davinci-resolve-lua-mcp.mcpb) (the latest release; the release notes and the SHA-256 are on the [Releases page](https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest)).
2. Double-click the file, or drag it onto the Claude Desktop window. Claude Desktop shows the extension's details and four settings; keep the defaults and click **Install**.
3. In Resolve, open a project and click `Workspace > Scripts > resolve_mcp_bridge`. The extension put that script there when it first started; Resolve's Console stays silent, which is expected.
   - The script 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 instead, which downloads the file and opens the same install dialog:

```sh
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
```

To update, download again from the same link (or rerun the command) and open the file; extensions installed from a file do not update on their own. To build the bundle yourself, see [Development](#development).

## Start and stop the bridge

1. In Resolve, open a project.
2. Click `Workspace > Scripts > resolve_mcp_bridge`.
3. Nothing appears in Resolve's Console. That is expected: the free edition mutes `print` in menu scripts. The script is now looping in the background and Resolve stays responsive.
4. In Claude Desktop, ask for the bridge status or just start working. `resolve_status` reports `alive: true`, the product, version, edition, page and open project.

<img src="docs/images/scripts-menu.png" width="600" alt="Resolve's Workspace > Scripts menu listing claude_diag and resolve_mcp_bridge">

> [!IMPORTANT]
> The script lives and dies with Resolve. After every Resolve launch, click `Workspace > Scripts > resolve_mcp_bridge` again before using the tools. The bridge 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 a loop is running is harmless: the new loop takes over and the old one exits on the first request addressed to the newer session.

## Example prompts

```text
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

| Tool | What it does | Parameters | Access |
|---|---|---|---|
| `resolve_status` | Whether the bridge is running and why not, its session, the self-install outcome and, when alive, product, version, edition, page and project | none | read-only |
| `run_lua` | Runs a Lua 5.1 chunk inside Resolve with the live `resolve` object; returns its first return value as JSON plus captured prints and errors | `code`; `timeout_s` 1..300 (default from the settings) | destructive |
| `get_project_info` | Name, page, database, frame rate, resolution, timeline count, root-bin counts and the current timeline of the open project | none | read-only |
| `list_projects` | Projects in the current project-manager folder with dates and notes; marks the open one | none | read-only |
| `list_timelines` | Every timeline with unique id, frame range and track counts; marks the current one | none | read-only |
| `list_media_pool_clips` | Clips in one bin with path, duration, fps, resolution, type, frames and colour | `bin_path` (default `/`); `offset`; `limit` 1..200 (default 50) | read-only |
| `get_timeline_items` | Items on one track of the current timeline with type, frames, source frames, enabled state and file path | `track_type` video, audio or subtitle; `track_index` from 1; `offset`; `limit` 1..500 (default 100) | read-only |
| `add_marker` | Adds a marker to the current timeline and returns the stored marker | `frame` (relative to the timeline start); `color` (one of the 16 Resolve colours); `name`; `note`; `duration` in frames (default 1) | writes |
| `delete_markers` | Deletes every marker of one colour, or all markers, from the current timeline | `color` (omit for all); `confirm` must be `true` | destructive |
| `set_current_timeline` | Makes the named timeline current; an unknown name lists the known ones | `name` | writes |
| `open_project` | Loads the named project, saving the open one first by default; an unknown name lists the known projects | `name`; `save_current` (default `true`) | writes |
| `render_current_timeline` | Queues and starts a render of the current timeline and returns the job id | `preset` (optional, validated against the preset list); `output_dir` (absolute, must exist); `filename` | writes |
| `get_render_status` | Status, completion percentage and error of one render job, plus whether Resolve is rendering | `job_id` | read-only |
| `stop_bridge` | Asks the bridge loop to exit cleanly; relaunch it from `Workspace > Scripts` afterwards | none | writes |
| `scripting_api_docs` | Searches Blackmagic's shipped scripting reference (`.pyi` signatures, README sections, CHANGELOG) with file and line; flags deprecated and unsupported calls | `query`; `limit` 1..10 (default 5) | read-only |

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.

<details>
<summary>Writing Lua for <code>run_lua</code></summary>

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 t