Davinci Resolve AI Bridge MCP

DaVinci Resolve AI Bridge MCP

Let your AI assistant help with the edit. Resolve AI Bridge connects Claude, Codex, Cursor, Antigravity, and other MCP-compatible assistants to the project open in DaVinci Resolve Free or Studio.

Inspect a timeline, place media, animate a zoom, adjust color, or try an edit on a duplicate timeline before touching the original.

Built to stay light

• Works with Resolve Free. No Studio license needed for the bridge. Individual tools still depend on your Resolve build; Studio-only effects stay Studio-only.
• One click to start. Choose Start AI Bridge in Resolve. Your AI gets the same tools and access as the old Console-paste workflow.
• A small, local runtime. No remote bridge server or manually entered token. Website dependencies stay out of the CLI package; FFmpeg and Remotion are optional.
• Keep your tokens for the edit. The launcher starts locally, without an AI request or extra startup tools.

⭐ Finding it useful? Give the bridge a star—it helps other editors find it.

---

Quick setup

You'll need Python 3.10+ (download).

Option A: Run directly with npx (Recommended for Node / npm users)

npx davinci-resolve-ai-bridge-mcp

Option B: One-line shell install

macOS / Linux (run in Terminal):

curl -fsSL https://raw.githubusercontent.com/flamexnreal/davinci-resolve-ai-bridge-mcp/main/install.sh | bash

Windows (run in PowerShell):

irm https://raw.githubusercontent.com/flamexnreal/davinci-resolve-ai-bridge-mcp/main/install.ps1 | iex

From a downloaded/cloned repository, run python3 install.py --with-ffmpeg (Windows: py install.py --with-ffmpeg), or use install-macos.command / install-windows.bat for the base install.

Node/npm is only needed for the npm installer and optional website/motion-graphics development.

The installer sets up ~/.resolve-ai-bridge, a private Python environment, the Resolve menu entries, editing skills, and detected supported AI clients. Valid client configs are backed up and merged; invalid configs are left unchanged with a diagnostic. Antigravity and other clients can use the generated mcp-config.json manually.

Wait for INSTALL COMPLETE, then reopen Resolve. If setup stops after downloading, see installer troubleshooting.

Optional: add FFmpeg for source frames and audio

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.

---

Connect to Resolve

1. Open DaVinci Resolve with a project.
2. Choose Workspace → Scripts → Resolve AI Bridge → Start AI Bridge. It may appear under Utility.
3. Ask your AI: “Call resolve_status, then bridge_capabilities and timeline_overview.” Open or create a timeline before using timeline tools; status works without one.

Start from the menu and get editing. Start once per Resolve session. You can see RESOLVE AI BRIDGE READY in Workspace → Console. Use Stop AI Bridge in the same menu to stop the worker; an active operation finishes first. Clicking Start again won't create another worker.

If the menu is missing after installation, quit and reopen Resolve once. Refresh/restart your AI client's MCP server after setup or a tool-schema update.

Menu startup is live-tested on macOS / Resolve Free 21.0.3.7 / Python 3.14.6. Windows, Linux, and other builds still need live verification; the Console fallback stays available.

Console fallback and startup details

If automatic startup reports an error on your build, open Workspace → Console, select Py3, paste this fallback command and press Enter:

import os;exec(open(os.path.expanduser("~/.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. Windows/Linux and other Resolve builds still require live verification; the portable fallback remains available.

Resolve may keep the menu script marked busy while its separate fuscript process serves requests. Resolve's editing UI remains usable. Closing Resolve ends that process. The Console fallback uses a daemon worker with a startup handshake capped at one second. No new dependency, listening port, public MCP tool, or AI call is added.

Studio: connect automatically with external scripting

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.

---

What you can do

Full MCP tool list

Motion graphics with Remotion

For custom typography, lower thirds, or animated callouts, your AI can create a Remotion video and import it with append_media. Remotion is a separate, optional toolchain; it isn't bundled into the bridge's Python runtime.

Motion graphics workflows · Editing recipes

---

A few things to know

Free support doesn't unlock Studio features. Source frames exclude timeline effects, and source audio isn't the Fairlight mix. Some edits have limits: splits rebuild clips, title text is best effort, and silence cuts are restricted to supported clip layouts.

Editing workflow, clip IDs, and frame/timecode rules

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.

Tool compatibility and limitations

• Free edition: New review workflows use ordinary timeline, marker and clip APIs through the Console worker. No Studio AI transcription, Magic Mask, Smart Reframe, or neural feature was added. Calls check their results and report unsupported behavior.
• 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 in front of MediaOut, so they stack and your own Fusion nodes stay connected. Resets remove only bridge-owned nodes. Every result reports the chain and whether values read back. These effects are tested against a simulated Fusion comp that runs the generated Lua in LuaJIT, not yet against a live Resolve. Check them 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.

---

Connect your AI client

Most setup is handled by the installer. For manual configuration, use the absolute-path entry in ~/.resolve-ai-bridge/mcp-config.json. No token needs to be typed into your client; the server and worker share a local token file automatically.

Codex / ChatGPT desktop setup

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.

Other clients, npm server mode, and generated commands

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.

---

Troubleshooting & updates

If the bridge is offline, open a project and choose Start AI Bridge. Run the doctor from the repository for a connection check:

python3 tools/doctor.py

Use python3 tools/doctor.py --offline for file checks without contacting Resolve.

Before an update, stop the worker and your MCP clients. The installer validates the replacement before activating it and keeps the previous runtime for recovery.

Troubleshooting · Testing · Release notes

Request safety, timeouts, and update recovery

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 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. The worker cleans up on its own: completed/failed records after 7 days, running records after 30 days, unread replies after an hour, and it rotates its log at 1 MB. A newly submitted request has a new ID.

Direct attach falls back to Console only before dispatch. 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.

Development and verification

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. There is no hosted CI yet, so run these checks locally before a release. Install the optional lupa package (python3 -m pip install lupa) to run the Fusion Lua tests too; without it they are skipped. Maintainers: see release instructions.

---

License

MIT. See LICENSE.