davinci-resolve-mcp MCP工具

Requirements

- DaVinci Resolve 18.5+ on macOS, Windows, or Linux. Studio supports external scripting directly. The free edition does not — Blackmagic gates external scripting to Studio — but it is still reachable through the in-app bridge, which runs inside Resolve from the ungated Workspace ▸ Scripts menu. - Python 3.10+ (3.10-3.12 is the lowest-risk range). Python 3.13/3.14 also work on recent Resolve builds (verified on Studio 20.3.2); older builds may fail to connect on 3.13+, in which case use 3.10-3.12. - Resolve external scripting set to Local (Studio). On the free edition this preference has no effect — use the in-app bridge instead.

Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+. They are live-tested on Studio 21.0.2.4 — see the Resolve 21 delta. Note that AnalyzeForIntellisearch, AnalyzeForSlate and GenerateSpeech each require a separately-downloaded AI Extras pack, and Resolve reports a missing pack inconsistently (some return False, others an error string), so these actions report success: false with the Resolve-supplied reason rather than guessing.

Quick Start

npx davinci-resolve-mcp setup

Before connecting, open DaVinci Resolve Studio and set Preferences > General > External scripting using to Local. (On the free edition that preference does not help — see Free edition below.) The npm launcher installs a managed copy under your user application-data directory, then runs the universal Python installer. The installer creates a virtual environment, detects Resolve paths, and can configure Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, Codex CLI, and JetBrains IDEs.

For source installs:

git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
cd davinci-resolve-mcp
python install.py

For platform paths, client-specific config, and manual setup, see Installation and Configuration.

The installer and server check the latest GitHub release for MCP updates. Checks are best-effort and throttled; the server never blocks MCP startup for a prompt. The installer can prompt, snooze, ignore a release, disable checks, or apply an opt-in safe auto-update for clean git checkouts.

Advanced server — beyond the scripting API (optional, Node)

The same package ships a second, optional MCP server: davinci-resolve-advanced-mcp (bin bin/davinci-resolve-advanced-mcp.mjs). Where the Python server drives a live Resolve over the sanctioned scripting API, the advanced server does what the API can't — it reads and edits Resolve files (.drp / .drt / .drx) and applies DB/XML-level changes with no Resolve running, so it runs cloud or local. 18 tools: drp, drt, drx (per-clip grade codec plus a deterministic, offline grading/QC catalog — within-camera + cross-camera skin (v2 skin-line metric) + b-roll + neutral-patch WB matching, match-to-reference, saturation/black-balance, contrast-normalize, ASC CDL import, lossless grade-transfer + season-look authoring, named-LUT attach, scope reads + intent tags, verify-grade, display-referred frame extraction, broadcast-legal QC), offline_ref, conform (frame-oracle conform/relink QC + lineage), color_trace (carry grades across a re-conform), fusion, audio_plan, fairlight (bus routing), audio, project_read, project_db, pipeline (a DB-as-truth pipeline: compile YAML project specs into a canonical SQLite DB, then run stages with gates, provenance, and intent↔actual drift detection), capabilities, deliverable (deliverable QC / compliance), media (media front-end / AE ingest), editorial (editorial integrity / changelist), provenance (provenance / audit / episode report). It can also be consumed as a library (importable engine API), not just spawned as a server.

DRX grade writes are live-calibrated against Resolve Studio: grade params take Resolve's on-screen panel units by default (space: 'ui' | 'drx'), and the structural writes (power windows, qualifiers, HDR zones, HSL curves, ColorSlice, blur/key/motion-effects) are panel-readback-verified — per-control status in resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md. It also closes a UI-only gap: programmatic "Cleanup Node Graph" (drx relayout for one clip, project_db relayout_node_graphs for a whole project) — node layout tidied, grade content byte-preserved.

Add it alongside the live server (both ship in one npm install):

{
  "mcpServers": {
    "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
    "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
  }
}

install.py prints both entries. The core is pure-JS/MIT with no required native modules; a few features need user-installed tools (ffmpeg for audio, sharp/better-sqlite3 for some paths) — call the capabilities tool for live status and install hints.

Unlike the Python server, this one has Node dependencies. npx davinci-resolve-mcp setup installs them into the managed install (npm install --omit=dev --omit=optional under resolve-advanced/) and only then registers the bin. If that install could not run — offline, or npm unavailable — setup registers an npx command for the advanced server instead, so the entry it writes always boots. To repair an existing install without re-running setup: npx davinci-resolve-mcp sync.

Operation envelope

Every compound tool return carries an _operation block beside its payload, so an agent reads one shape instead of a different key per tool: status (success / partial / blocked / failed), verification (with contradiction kept distinct — Resolve reported success and the readback disagreed), changes (the semantic delta), warnings, and an execution_id.

Two absences are meaningful and deliberate. verification.status: "unverified" means no evidence was reported, not "checked and clean". A missing changes means the action did not report a delta, not that nothing changed — an empty {} there would be a confident, wrong answer about an edit that simply never declared one.

The envelope is namespaced rather than merged into the top level because status, operation, warnings, result and changes are all already domain keys here; flattening would rewrite a background job's status: "done" and a confirm gate's status: "confirmation_required". `setup(action="set_defaults", params={"result_envelope": "pure" | "legacy"})` changes the shape, per call via params={"envelope": ...}, per process via RESOLVE_MCP_RESULT_ENVELOPE.

Optional Extras

The core install is deliberately small: Python, ffmpeg, and the Resolve scripting API. Some features need more, and each one refuses honestly with its own install line rather than degrading into a guess — a fabricated tempo or an invented level produces confident, wrong output, which is worse than no feature.

Run python scripts/doctor.py to see which of these you have.

media_analysis action capabilities reports the analysis stack in detail and tells you what each missing piece would enable.

Nothing here is bundled. Model weights carry their own licences separate from the code that loads them; check them before commercial use.