Davinci Resolve AI Bridge MCP README

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.

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 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.

• 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.
• 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 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. Records persist until manually removed with workers/clients stopped; removing them removes duplicate protection. 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.

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. CI tests Python on macOS, Windows and Linux and checks website/package builds. Maintainers: see release instructions.