Davinci Resolve AI Bridge MCP

For Free-compatible source frame capture and efficient audio decoding, also install the optional private FFmpeg binary:

npx davinci-resolve-ai-bridge-mcp --with-ffmpeg

This optional download stays in the bridge's private Python environment. It is not a Studio dependency. An existing ffmpeg on PATH also works; macOS afconvert supports audio extraction without FFmpeg.

On Free 21.1+, open Workspace → Console, select Lua, paste this portable fallback and press Enter:

if fusion:GetData("ResolveAIBridge.NativeApp")~=tostring(fusion) then fusion:RunScript((os.getenv("RESOLVE_AI_BRIDGE_HOME") or ((os.getenv("USERPROFILE") or os.getenv("HOME")).."/.resolve-ai-bridge")).."/ResolveLua.lua") end

On Python-enabled builds, select Py3 and use:

import os;exec(open(os.path.join(os.path.expanduser(os.getenv("RESOLVE_AI_BRIDGE_HOME") or "~/.resolve-ai-bridge"),"ResolveConsole.py"),encoding="utf-8").read())

Live startup validation: macOS, DaVinci Resolve Free 21.0.3.7, Python 3.14.6: menu start, real status requests, repeated start, Stop, quit/reopen/start, and Console fallback passed. The separate native-file Lua connector supports the tested Free 21.1.2 build. Windows/Linux and other builds still need live verification.

The Lua menu worker stays in its native script context and uses bmd.wait between requests, keeping the editing UI usable. The Python menu route keeps a separate fuscript process alive; its Py3 fallback starts a daemon worker and returns after a short handshake. The Lua worker uses signed local file messages, with no socket or FFI dependency. No public MCP tool or AI startup call is added.

Studio can use the same menu workflow. To allow direct attach, set Preferences → System → General → External scripting using → Local. When external scripting is available, the bridge connects directly. It probes that connection in a disposable process and uses the Console transport when direct attach is unavailable.

1. Call resolve_status and timeline_overview.
2. Use each clip's id, which uses its Resolve unique ID when available. label values such as V1.2 remain accepted but can change after insertions/deletions. Rebuilt and duplicated clips have new IDs.
3. Call preview_timeline before a batch of changes. It creates and opens a copy while keeping the original.
4. Get fresh IDs from timeline_overview, make edits, and inspect after each change.
5. Use compare_timelines(original, preview) to review structural changes. Audition/view the result in Resolve too: the comparison does not render pixels or compare all Fusion, color, or Fairlight data.

All public frame inputs and clip start/end positions use absolute timeline frames. Marker offsets are relative to timeline start. Timecodes support non-drop-frame and 29.97/59.94 drop-frame (HH:MM:SS;FF). Cut end positions are exclusive.

Fusion effects (animate_zoom, blur, spotlight, saturation, color fx) are the exception, because they live inside one clip: start_frame, end_frame and keyframe frame count from the clip's first frame (0). Pass timeline_start_frame, timeline_end_frame or keyframe timeline_frame to use absolute timeline frames instead.

• Free edition: Use the native-file Lua worker on Free 21.1+. It uses ordinary timeline, marker, clip and Fusion APIs and shares the existing Python editing implementation outside Resolve. No Studio AI transcription, Magic Mask, Smart Reframe, or neural feature was added.
• Frame images: Source fallback shows decoded source media, not the graded/composited viewer. It omits Fusion, transforms and overlays. mode="composite" fails explicitly if a composited still is unavailable. Without a resize utility, actual dimensions are reported rather than invented.
• Audio: Analysis reads source PCM, not the Fairlight mix. It excludes timeline gain, fades, mute, effects and retiming. Known source retiming is rejected. Silence uses 50 ms windows, not speech transcription. Results include the source offset, absolute timeline origin, exclusive ends and a truncation flag; default analysis limit is 300 seconds.
• Splits: Fusion clips, locked tracks, mixed rates and known retiming are rejected before deletion. A checkpoint is retained. Rebuilt clips restore static transforms, enabled state, clip color and the current color-grade layer. Audio links, fades, keyframes, other grade layers and all metadata are not guaranteed. On failure, the tool opens the checkpoint and reports any partial attempted timeline honestly.
• Dialogue cuts: Automatic application is restricted to one isolated clip or one aligned video/audio pair. It rejects stale review markers and complex multi-clip timelines. The original is kept intact. Review audio gain, fades and non-review markers on the result.
• Fusion effects: Zoom, blur, spotlight, saturation and color fx share one bridge-owned chain before MediaOut. Effects, speed and resets passed live checks through the Lua connector on macOS Free 21.1.2.10 and through Python on Free 21.0.3.7. Tests also cover preserving user nodes. Other builds, Studio and large comps need verification; inspect results with inspect_fusion or the Fusion page.
• Speed: Fusion mode changes video timing inside the clip, not timeline duration or linked audio. Resetting to 1× neutralizes only the updated bridge's own node; user-created and older untagged TimeSpeed nodes are left alone. Reverse mapping is not verified and is rejected. Clip-attributes mode changes all uses of that media, multiplying its current source FPS; it is not a per-clip reset or speed ramp.
• Validation: Automated tests cover mocked Resolve operations, source decoding and MCP responses. They do not certify every operation on every Free-version build or platform. See testing guidance for the manual integration checklist.

The installer registers the bridge when it finds the Codex CLI. Check with:

codex mcp get resolve-ai-bridge

If needed, register the installed runtime on macOS/Linux:

codex mcp add resolve-ai-bridge -- "$HOME/.resolve-ai-bridge/.venv/bin/python" "$HOME/.resolve-ai-bridge/bridge/server.py"

On Windows PowerShell:

codex mcp add resolve-ai-bridge -- "$HOME/.resolve-ai-bridge/.venv/Scripts/python.exe" "$HOME/.resolve-ai-bridge/bridge/server.py"

Restart/refresh the MCP server in the desktop app after setup or a tool-schema update. Start a new task and ask: “Call resolve_status, then bridge_capabilities and timeline_overview.” With no timeline open, resolve_status can still confirm the project connection.

The ChatGPT desktop app and local Codex clients on the same host share the Codex MCP configuration. ChatGPT web does not read this local configuration; remote plugin/tunnel setup is a separate integration and is not installed by this project. See official MCP setup documentation.

For lengthy source analysis, the optional Codex server setting tool_timeout_sec = 180 allows more time than its default timeout. Keep it inside the existing [mcp_servers.resolve-ai-bridge] table.

Use the absolute-path server entry generated at ~/.resolve-ai-bridge/mcp-config.json. The installer also writes claude-command.txt and codex-command.txt there.

For clients that support npm commands, install first, then start the server with the explicit --serve mode:

{
  "mcpServers": {
    "resolve-ai-bridge": {
      "command": "npx",
      "args": ["-y", "davinci-resolve-ai-bridge-mcp", "--serve"]
    }
  }
}

npx davinci-resolve-ai-bridge-mcp without --serve is the installer, not an MCP stdio process. Prefer the generated absolute Python command for predictable offline startup. The installer-created resolve-ai-bridge launcher starts the server directly; npm's executable with the same name requires --serve.

No token is needed in the client configuration. The server and Console worker share a local token file automatically.

Console requests carry a unique ID, deadline, worker session and the project/timeline IDs last observed by that MCP client. Inspect resolve_status or timeline_overview in each client before its first queued edit. Mutations validate that context immediately before execution; stale or unavailable IDs are rejected. Restart the Console worker after updating: older workers are refused by the new client. Only one Console worker should use a runtime directory.

The Lua route signs local request/reply/heartbeat bytes with HMAC-SHA256. Complete operations hold a cross-process lock and native lease; object handles and Stop requests belong to one session. Partial file reads are retried without resending edits. An uncertain response halts further native calls, records an unknown outcome and requires fresh inspection. Lua's heartbeat runs between native calls and can pause during a long native call; it is not a progress guarantee.

The heartbeat reports busy, state (running, completed, failed, or initial idle) and request_id. Its reporting thread makes no Resolve API calls; project/timeline details are cached during jobs. A fresh heartbeat proves the Python reporter is alive, not that a native operation is making progress. A native call holding Python's GIL may still prevent heartbeat updates.

A client timeout stops waiting; it does not confirm cancellation. Queued requests expire before execution, but active native work can finish later. Inspect ~/.resolve-ai-bridge/requests/<request-id>.json and the timeline before attempting another edit. Completed/failed records retain results; a surviving running record after a crash means an unknown outcome and prevents replay of that ID. This is duplicate suppression, not an exactly-once guarantee. Completed/failed records are cleaned up after 7 days; running and explicit Lua unknown records stay for 30 days. The Python worker runs cleanup while active; the Lua transport runs it on tool calls, at most once every 10 minutes per MCP process/runtime. Cleanup also removes unread Python replies after an hour and rotates its log at 1 MB. A newly submitted request has a new ID.

In auto mode, direct attach falls back to Console only before dispatch. Forcing RESOLVE_AI_BRIDGE_MODE=direct disables worker fallback and reports offline if direct attach is unavailable. Unexpected exceptions after dispatch report an unknown outcome without replay. UI switches during native execution cannot be locked out: keep the intended project/timeline open while edits run. Context validation catches mismatches immediately before execution, not switches away and back between observations.

Before updating, stop the Console worker and MCP clients. The installer builds and validates a staged runtime and dependencies before activation, retains the old directory at ~/.resolve-ai-bridge.previous, and restores it on a caught activation failure. A hard interruption can leave a sibling .install-lock and .stage-* directory; see troubleshooting for recovery. Configuration/menu registration follows activation and is not one transaction with it. Run python3 tools/doctor.py --offline for file diagnostics without contacting Resolve.

python3 -m pip install -r requirements.txt
python3 -m unittest discover -s tests -v
node tools/check-package.mjs
python3 tools/doctor.py

Website development dependencies are separate from the published CLI's runtime dependencies:

npm ci
npm run build

The package check creates and inspects a temporary npm tarball; it does not publish. GitHub Actions runs the suite, package check, website build and dependency audit on Linux, macOS and Windows. Install optional lupa (python3 -m pip install lupa) to run the Fusion Lua tests too. Maintainers: see release instructions.