davinci-resolve-mcp
This MCP server lets an AI agent control DaVinci Resolve through a local file-polling Lua bridge.
Check bridge health and Resolve status/version/current page/project/timeline.
Manage projects: save, list, create, and load projects.
Switch workspace pages and manage timelines: create, list, and activate by name or index.
Read and set the playhead timecode.
Add, list, and delete timeline markers with name, note, color, duration, and frame.
Import media files into the Media Pool and create bins.
Start/stop rendering and check render status.
Provides tools for controlling DaVinci Resolve Free (and Studio) through a local file-polling bridge, enabling project and timeline management, media import, playhead and marker operations, workspace page switching, rendering control, and status checks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@davinci-resolve-mcp create a new timeline called Rough Cut"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DaVinci Resolve Free Edition AI Bridge
A transparent, zero-dependency, local file-polling bridge that allows external AI agents, MCP servers, and CLI tools to control DaVinci Resolve Free (and Studio).
Unlike the Studio edition, the Free version blocks external Python connections (DaVinciResolveScript) and the built-in MCP server. This project bypasses that restriction securely using native Lua scripting and local atomic file transactions—no third-party extensions, no network sockets, and no compiled binaries required.
🚀 How It Works
The Lua Script (
CustomAILink.lua) runs inside DaVinci Resolve's native Lua scripting engine.It uses non-blocking polling (
bmd.wait()) every 250ms, yielding execution so Resolve's user interface never stutters or freezes.Your AI Agent / CLI / MCP Server writes a command to the bridge directory:
Structured JSON:
resolve_cmd.json(includes requestid,command, and typedparams).Plain Text:
resolve_cmd.txt(simple single-line commands).
Resolve reads the command, verifies it against an allowlist, safely executes the operation via the official Resolve API, and atomically writes the result to
resolve_resp.json.
Related MCP server: davinci-resolve-mcp
🛠️ Installation & Setup
Step 1: Copy the Script to Resolve
On macOS/Linux, run scripts/install_lua.sh to copy it into the per-user Scripts/Utility folder. Otherwise copy lua/CustomAILink.lua manually to your DaVinci Resolve scripts directory:
macOS:
Utility (accessible from all pages - Recommended):
~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility/Comp (Fusion page):
~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Comp/
Windows:
Utility (Recommended):
%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Scripts\Utility\Comp:
%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Scripts\Comp\
Linux:
Utility:
$HOME/.local/share/DaVinciResolve/Fusion/Scripts/Utility/
Step 2: Start the Bridge
Open DaVinci Resolve Free and load any project.
In the top menu, go to Workspace > Scripts > Utility > CustomAILink (or Scripts > Comp > CustomAILink).
The DaVinci Resolve Console will open, displaying:
================================================================== DaVinci Resolve Free AI File-Polling Bridge (CustomAILink) Status: ACTIVE & LISTENING Bridge Directory: /tmp/davinci_resolve_bridge Watching Files: - JSON: /tmp/davinci_resolve_bridge/resolve_cmd.json - TXT: /tmp/davinci_resolve_bridge/resolve_cmd.txt Connected To: DaVinci Resolve v... ==================================================================
🤖 Interacting with the Bridge
1. Structured JSON (Recommended for AI Agents & MCP Servers)
Write to /tmp/davinci_resolve_bridge/resolve_cmd.json (or %TEMP%\davinci_resolve_bridge\resolve_cmd.json on Windows):
{
"id": "req-001",
"command": "CREATE_TIMELINE",
"params": {
"name": "Rough Cut - Episode 1"
}
}Resolve executes the command and atomically writes /tmp/davinci_resolve_bridge/resolve_resp.json:
{
"id": "req-001",
"command": "CREATE_TIMELINE",
"status": "success",
"data": {
"created": true,
"timeline_name": "Rough Cut - Episode 1",
"current_timecode": "01:00:00:00",
"start_frame": 86400
},
"error": null,
"timestamp": 1730172900
}2. Quick Plain Text (CLI / Terminal)
You can also send quick terminal commands directly:
# macOS / Linux
echo "CREATE_TIMELINE Rough Cut" > /tmp/resolve_cmd.txt
echo "SAVE_PROJECT" > /tmp/resolve_cmd.txt
echo "OPEN_PAGE edit" > /tmp/resolve_cmd.txt
# Windows (Command Prompt)
echo CREATE_TIMELINE Rough Cut > %TEMP%\resolve_cmd.txt
echo SAVE_PROJECT > %TEMP%\resolve_cmd.txt🔌 MCP Server & CLI
The Python package wraps the bridge and exposes every command as a typed MCP tool. It requires the Lua bridge to be running inside Resolve.
Option 1: Standalone Installation (Recommended for Daily Use)
Install directly into your global tool environment with uv:
uv tool install git+https://github.com/allensandiego/davinci-resolve-mcpAdd to your MCP client config (e.g. Claude Desktop, Antigravity, Cursor):
{
"mcpServers": {
"davinci-resolve": {
"command": "davinci-resolve-mcp"
}
}
}(Or specify the absolute binary path, e.g. ~/.local/bin/davinci-resolve-mcp)
Alternatively, run on demand without prior installation using uvx:
{
"mcpServers": {
"davinci-resolve": {
"command": "uvx",
"args": ["--from", "git+https://github.com/allensandiego/davinci-resolve-mcp.git", "davinci-resolve-mcp"]
}
}
}Option 2: Local Development
If you are modifying or extending the bridge:
git clone git@github.com:allensandiego/davinci-resolve-mcp.git
cd davinci-resolve-mcp
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'Testing the Bridge
Send commands manually via the CLI:
resolve-cli ping
resolve-cli create_timeline '{"name": "Rough Cut"}'Run integration tests (these launch the Lua bridge under Resolve's fuscript; set FUSCRIPT if it is located elsewhere):
pytestSet DAVINCI_BRIDGE_DIR to override the bridge directory (must match on both sides).
🗂️ Project Layout
lua/CustomAILink.lua Resolve-side bridge (runs inside Resolve)
src/davinci_resolve_mcp/ Python package: client.py, server.py (MCP), cli.py
tests/ pytest integration tests (use fuscript)
scripts/install_lua.sh Installs the Lua script into Resolve📜 Supported Command Reference
Command | Parameters | Description |
| none | Health check; returns product version, bridge directory, and Studio flag. |
| none | Retrieves active project status, timeline count, active timeline, and current page. |
| none | Saves the currently open project. |
| none | Lists all projects in the current database folder. |
|
| Creates a new project in the active database folder. |
|
| Loads a project by name. |
|
| Switches workspace page ( |
|
| Creates an empty timeline in the active project. |
| none | Returns a list of all timelines, their start/end frames, and current timecodes. |
|
| Activates the specified timeline. |
| none | Gets current playhead timecode and frame bounds. |
|
| Moves the playhead to the specified timecode. |
|
| Adds a marker to the active timeline. Colors: Blue, Cyan, Green, Yellow, Red, Pink, Purple, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa, Cream. |
| none | Returns all markers on the current timeline. |
|
| Removes a marker at the specified frame ID. |
|
| Imports media files into the active project's Media Pool. |
|
| Creates a subfolder/bin inside the Media Pool. |
| none | Starts rendering the current render queue. |
| none | Stops an active render job. |
| none | Checks if rendering is currently in progress. |
| none | Gracefully stops the listener loop inside Resolve. |
🛡️ Security & Hardening
Strict Command Allowlist: All incoming commands are dispatched through a fixed whitelist table. The bridge rejects any unknown commands and never evaluates dynamic code via
loadstringoros.execute.Protected Error Isolation (
pcall): Every Resolve API interaction runs within protected calls. Unhandled API errors or missing open projects return structured error payloads without crashing the listener loop.Atomic File Operations: Responses are written to temporary files (
.tmp) and swapped atomically using rename semantics to prevent race conditions or half-read payloads by client agents.Zero Network Attack Surface: Communicates strictly via local filesystem transactions in secure temporary directories (
/tmp/davinci_resolve_bridgeor%TEMP%).
📄 License
MIT License.
Available Tools
20 toolsadd_markerC
Add a marker to the active timeline (defaults to the start frame).
Inputs: name, note, color, duration, +1 more.
create_binC
Create a Media Pool bin.
Inputs: name (required).
create_projectD
Create a new project.
Inputs: name (required).
create_timelineC
Create an empty timeline in the current project.
Inputs: name.
delete_markerC
Delete the marker at a frame.
Inputs: frame_id (required).
get_current_timeA
Get the playhead timecode of the active timeline.
Inputs: no named parameters.
get_markersC
Get markers on the active timeline.
Inputs: no named parameters.
get_render_statusB
Check whether a render is in progress.
Inputs: no named parameters.
get_statusA
Get Resolve version, current page, open project and active timeline.
Inputs: no named parameters.
get_timelinesB
List all timelines in the current project.
Inputs: no named parameters.
import_mediaC
Import media files (absolute paths) into the Media Pool.
Inputs: paths (required).
list_projectsB
List projects in the current database folder.
Inputs: no named parameters.
load_projectC
Load an existing project by name.
Inputs: name (required).
open_pageB
Switch page: media, cut, edit, fusion, color, fairlight or deliver.
Inputs: page (required).
pingA
Check that the bridge is running inside DaVinci Resolve.
Inputs: no named parameters.
save_projectB
Save the currently open project.
Inputs: no named parameters.
set_current_timeC
Move the playhead, e.g. '01:00:10:00'.
Inputs: timecode (required).
set_current_timelineC
Activate a timeline by name or 1-based index.
Inputs: name, index.
start_renderB
Start rendering the current render queue.
Inputs: no named parameters.
stop_renderB
Stop the active render.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool maps to a clearly distinct resource or action: project management, timeline control, marker operations, media import, and render control are separated cleanly. The only potentially broad tool, get_status, is distinct from ping because it returns project/timeline/page context rather than just bridge health.
Most tools follow a predictable snake_case verb_noun pattern such as create_project, get_timelines, set_current_time, and delete_marker. Minor deviations exist: ping is a standalone health-check verb, and get_timelines is plural while create_timeline is singular.
Twenty tools is slightly above the ideal compact range, but the server covers several distinct DaVinci Resolve areas: projects, pages, timelines, playhead, markers, media, and rendering. Each tool has a plausible role, so the count is reasonable though somewhat heavy.
The surface covers important project, timeline, marker, media import, and render basics, but has notable gaps. There are no delete/update operations for projects or timelines, no media pool listing or clip-level editing, and render queue job creation/configuration is missing, which can leave start_render as a partial dead end.
Maintenance
Related MCP Connectors
AI video editor for agents and humans: timeline, captions, color, audio and generation as MCP tools.
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceExposes 20 tools for project, media, render, and timeline control in DaVinci Resolve 18+ via stdio MCP, enabling AI agents to operate the software through natural language.54MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that exposes the complete DaVinci Resolve scripting API, enabling AI assistants to control DaVinci Resolve programmatically with over 440 tools for project management, timeline editing, color grading, rendering, and more.26MIT
- AlicenseBqualityAmaintenanceLets AI clients inspect and control DaVinci Resolve projects via MCP tools.46795 npm54MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to control DaVinci Resolve Studio via MCP, providing full scripting API coverage plus workflow helpers for editing, media organization, rendering, grading, and more.11,225 npmMIT