docs

DaVinci Resolve MCP Server — AI Skill Reference

This document gives AI assistants the context needed to use the DaVinci Resolve MCP server effectively. It covers the tool landscape, page prerequisites, common workflow patterns, error recovery, and known gotchas.

What This Server Does

The DaVinci Resolve MCP server bridges AI assistants to DaVinci Resolve Studio via its official Scripting API. You can control every aspect of a post-production session — projects, timelines, clips, color grading, Fusion compositions, audio, render queues, and more — through natural language.

DaVinci Resolve must be running with Preferences > General > "External scripting using" set to Local, or set to Network with RESOLVE_SCRIPT_HOST configured to the Resolve host IP (use 127.0.0.1 on the same machine). The server auto-launches Resolve if it is not running, but that first connection can take up to 60 seconds.

Free edition. Both of those preferences are Studio features; on the free edition scriptapp("Resolve") refuses a foreign process regardless. A third transport reaches it — a script run from Workspace ▸ Scripts is handed the live resolve object (measured on free 21.0.3.7) and re-exports it over an authenticated loopback listener. Resolve 21.1 moved Python scripting to Studio: on free 21.1 the Scripts menu no longer lists .py files (#203), so on that build expect the bridge to have no launch path until the Console is checked. Install with python scripts/install_resolve_bridge.py and start it from that menu; once running it is used automatically when external scripting is unavailable, with no environment variable needed. DAVINCI_RESOLVE_BRIDGE=1 forces it — the bridge becomes the only transport tried, so its faults surface directly instead of degrading to another path. Existing tool call sites work unchanged. Two things to know when diagnosing it:

• On macOS, Resolve finds Python 3 through PYTHON3HOME, then /usr/local/bin/python3 — and nowhere else, so Homebrew/pyenv/uv/conda interpreters simply never appear, with no error. python.org installs work because that installer creates /usr/local/bin/python3; framework-ness itself is not the variable (#143). The sudo-free fix is launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')" — launchctl, not export, because Resolve is GUI-launched and inherits launchd's environment. The installer preflights both routes and ships a Lua canary, which always lists, so "Python not detected" is distinguishable from "wrong folder". The preflight is macOS-only — off macOS Resolve finds Python by other means, and running the check there was a false alarm (#106). Two follow-ups from #182 worth having in hand when a user says the menu is empty despite a set PYTHON3HOME: the prefix needs both lib/libpython3.X.dylib and bin/python3 under that unversioned name (Homebrew framework builds often ship only python3.X, so half the check passes on the very interpreter people reach for), and launchctl setenv does not survive a reboot — a bridge that listed for weeks and then stopped, with no error anywhere, is usually that. sudo ln -s "$(command -v python3)" /usr/local/bin/python3 is the persistent alternative.
• Windows: both script folders confirmed. %PROGRAMDATA% (#109) and %APPDATA% (#112) have each been shown serving the bridge on Windows 11 free builds. If a user reports the menu entry missing on Windows, ask whether the Lua canary lists — that separates "wrong folder" from "Python not detected".
• A bridge that stops answering while its socket is LISTENING is a stale process, not a modal dialog. Before v2.70.3 the Windows bridge could never detect Resolve exiting (os.getppid() does not change there), so it outlived Resolve holding the port and answering with a dead handle — and the bridge_timeout message blamed a modal dialog. On any build, the way out is the shutdown operation (BridgeClient.bridge_shutdown()); killing the process is the fallback, not the first move.
• The control panel connects over the bridge too (fixed in v2.70.2). It runs as a separate process with its own connector, so a panel that reports "Resolve unavailable" while tool calls work is a panel-side bug, not a broken bridge.
• The in-Resolve runtime is a copy taken at install time. After changing the repository, re-run the installer and then ask the running bridge to reload — it re-imports from disk in place, so Resolve does not need restarting.