Skip to content
Back to search

davinci-resolve-mcp

MCP server integration for DaVinci Resolve Studio

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/samuelgursky/davinci-resolve-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/samuelgursky/davinci-resolve-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samuelgursky--davinci-resolve-mcp/badge.svg)](/listings/samuelgursky--davinci-resolve-mcp)

HTML

<a href="/listings/samuelgursky--davinci-resolve-mcp"><img src="/api/listings/samuelgursky--davinci-resolve-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#free-edition-in-app-bridge) 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](docs/install.md).

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 498 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DaVinci Resolve MCP Server
  2. English | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
  3. [![Version](https://img.shields.io/badge/version-5.3.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
  4. [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
  5. [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
  6. [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(390%20full)-blue.svg)](#server-modes)
  7. [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
  8. [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
  9. [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
  10. [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
  11. [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  12. A Model Context Protocol (MCP) server that lets AI assistants control DaVinci Resolve Studio through the official Scripting API. It provides full API coverage plus guarded workflow helpers for editing, media pool organization, render setup, review markers, grading, Fusion, Fairlight, project lifecycle tasks, extension authoring, and source-safe media analysis.
  13. [![Local control panel](https://raw.githubusercontent.com/samuelgursky/davinci-resolve-mcp/main/docs/images/control-panel/01-overview.png)](docs/guides/control-panel.md)
  14. A local browser control panel ships with the server for inspecting Resolve state, running source-safe analysis, drilling into analyzed clips and shots, and editing analysis output inline. See the [Control Panel Guide](docs/guides/control-panel.md) for the full tour.
  15. ## Quick Start
  16. ```bash
  17. npx davinci-resolve-mcp setup
  18. ```
  19. 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](#free-edition-in-app-bridge) 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.
  20. For source installs:
  21. ```bash
  22. git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
  23. cd davinci-resolve-mcp
  24. python install.py
  25. ```
  26. For platform paths, client-specific config, and manual setup, see [Installation and Configuration](docs/install.md).
  27. 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.
  28. ## Free edition (in-app bridge)
  29. Blackmagic gates *external* scripting to Studio: on the free edition
  30. `scriptapp("Resolve")` refuses a foreign process, whatever the preference says.
  31. Through Resolve 21.0.x the **Workspace ▸ Scripts** menu was not gated — a script
  32. launched from it is handed the live `resolve` object (measured on free 21.0.3.7) —
  33. so the server can reach the free edition through a small script that runs *inside*
  34. Resolve and re-exports it over an authenticated loopback listener. **Resolve 21.1
  35. moved Python scripting to Studio.** On free 21.1 the Scripts menu no longer lists
  36. `.py` files at all (reported on Fedora 44 in #203; a Lua script in the same folder
  37. lists normally). Whether the Console still runs Python there is unconfirmed, so
  38. treat the bridge as a 21.0.x path until that is measured.
  39. ```bash
  40. python scripts/install_resolve_bridge.py
  41. # restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge
  42. ```
  43. The installer and MCP client use `~/.config/davinci-resolve-mcp/bridge.json`
  44. by default. To keep the authenticated bridge config elsewhere, set
  45. `DAVINCI_RESOLVE_BRIDGE_CONFIG` while running the installer and in the MCP
  46. client environment; both sides will use that path.
  47. Once that listener is running it is used **automatically** whenever external
  48. scripting is unavailable — no environment variable required. Setting
  49. `DAVINCI_RESOLVE_BRIDGE=1` *forces* the bridge instead: it becomes the only
  50. transport tried, so a bridge that stops answering reports its own fault rather
  51. than quietly falling back to another transport. Use it when the bridge is the
  52. path you intend to depend on.
  53. On **macOS**, Resolve looks for Python 3 in exactly two places: the
  54. `PYTHON3HOME` environment variable, then `/usr/local/bin/python3`. Homebrew,
  55. pyenv, uv and conda land in neither, so the script silently never appears in the
  56. menu. A python.org install works because its installer creates
  57. `/usr/local/bin/python3` — but you do not need one: point Resolve at the
  58. interpreter you already have, no `sudo` required.
  59. ```bash
  60. launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"
  61. ```
  62. Use `launchctl setenv`, not `export` — Resolve is launched from the Dock and
  63. never sees your shell's environment. Restart Resolve afterwards. A Lua canary is
  64. installed alongside so you can tell "Python not detected" apart from a wrong
  65. folder.
  66. Two things that bite (#182). The prefix must contain **both**
  67. `lib/libpython3.X.dylib` and `bin/python3` under that exact **unversioned**
  68. name — Homebrew's framework builds often ship only `bin/python3.13`, which is
  69. half a Python as far as Resolve is concerned, and the installer's preflight now
  70. says so instead of reporting a usable prefix. And `launchctl setenv` **does not
  71. survive a reboot**; if scripts stop listing weeks later with no error, that is
  72. why. For something persistent, put an interpreter where Resolve already looks
  73. (this one needs `sudo`, and check that `/usr/local/bin` does not precede your
  74. normal Python on `PATH`):
  75. ```bash
  76. sudo ln -s "$(command -v python3)" /usr/local/bin/python3
  77. ```
  78. Validated on free 21.0.3.7 and Studio 19.1.3.7, both macOS. The Windows paths
  79. added in v2.70.1 (issue #106) shipped unverified; reports on free 21.0.1.11
  80. (issue #109) and free 21.0.3.7 (issue #112) have since shown the bridge
  81. installing, listing and serving from **both** `%PROGRAMDATA%` and `%APPDATA%` on
  82. Windows 11, so those paths are now confirmed rather than assumed. Linux is
  83. confirmed as well: a report on free 20.3.2.9 (issue #129, Fedora 43) shows the
  84. bridge installing to `~/.local/share/DaVinciResolve/Fusion/Scripts/Utility`,
  85. listing against the system Python — Linux has none of this discovery problem —
  86. and serving end-to-end. No platform now rests on an assumption: macOS was
  87. validated directly, Windows and Linux on user reports.
  88. Note that the bridge holds its port for as long as it serves. Before v2.70.3 a
  89. Windows bridge could outlive Resolve and block the next session's listener; if
  90. you are on an older build and a bridge stops answering, check for a stale
  91. `fuscript.exe` still holding the port.
  92. This is the documented in-app path, not a licence circumvention, but Blackmagic
  93. could close it — treat it as a supported-until-it-is-not tier. Loopback only,
  94. HMAC-signed requests, one-use nonces.
  95. ## Local Control Panel
  96. Launch the single-user local control panel from the repository root:
  97. ```bash
  98. venv/bin/python -m src.control_panel
  99. ```
  100. The command starts a loopback-only server and opens the control panel in your browser at a URL that carries a per-launch access token (`http://127.0.0.1:8765/#token=…`) — use that exact URL; the panel refuses requests without it. To have an AI coding agent do this, ask: **"Open the Resolve MCP control panel for this repo."** Agents should use `venv/bin/python -m src.control_panel` unless your Python environment is already active. Persisted analysis jobs refresh the local search index automatically after successful slices; the manual Build Index action is for rebuilding from existing reports.
  101. ## Server Modes
  102. | Mode | Entry point | Tools | Best for |
  103. |------|-------------|-------|----------|
  104. | Compound | `src/server.py` | 37 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
  105. | Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 390 | Power users who want one MCP tool per Resolve API method. |
  106. The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
  107. ### Advanced server — beyond the scripting API (optional, Node)
  108. The same package ships a second, optional MCP server: **`davinci-resolve-advanced-mcp`** (bin
  109. `bin/davinci-resolve-advanced-mcp.mjs`). Where the Python server drives a *live* Resolve over the
  110. sanctioned scripting API, the advanced server does what the API **can't** — it reads and edits Resolve
  111. **files** (`.drp` / `.drt` / `.drx`) and applies DB/XML-level changes **with no Resolve running**, so it
  112. runs cloud *or* local. 18 tools: `drp`, `drt`, `drx` (per-clip grade codec **plus a deterministic,
  113. offline grading/QC catalog** — within-camera + cross-camera skin (v2 skin-line metric) + b-roll +
  114. neutral-patch WB matching, match-to-reference, saturation/black-balance, contrast-normalize, ASC CDL
  115. import, lossless grade-transfer + season-look authoring, named-LUT attach, scope reads + intent tags,
  116. verify-grade, display-referred frame extraction, broadcast-legal QC), `offline_ref`,
  117. `conform` (frame-oracle conform/relink QC + lineage), `color_trace` (carry grades across a re-conform),
  118. `fusion`, `audio_plan`, `fairlight` (bus routing), `audio`, `project_read`, `project_db`, `pipeline`
  119. (a **DB-as-truth pipeline**: compile YAML project specs into a canonical SQLite DB, then run stages with
  120. gates, provenance, and intent↔actual drift detection), `capabilities`, `deliverable` (deliverable QC /
  121. compliance), `media` (media front-end / AE ingest), `editorial` (editorial integrity / changelist),
  122. `provenance` (provenance / audit / episode report). It can also be consumed **as a
  123. library** (importable engine API), not just spawned as a server.
  124. DRX grade writes are **live-calibrated against Resolve Studio**: grade params take Resolve's
  125. on-screen panel units by default (`space: 'ui' | 'drx'`), and the structural writes (power windows,
  126. qualifiers, HDR zones, HSL curves, ColorSlice, blur/key/motion-effects) are panel-readback-verified —
  127. per-control status in `resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md`. It also closes
  128. a UI-only gap: **programmatic "Cleanup Node Graph"** (`drx` `relayout` for one clip, `project_db`
  129. `relayout_node_graphs` for a whole project) — node layout tidied, grade content byte-preserved.
  130. Add it alongside the live server (both ship in one `npm install`):
  131. ```json
  132. {
  133. "mcpServers": {
  134. "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
  135. "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
  136. }
  137. }
  138. ```
  139. `install.py` prints both entries. The core is pure-JS/MIT with no required native modules; a few features
  140. need user-installed tools (ffmpeg for `audio`, `sharp`/`better-sqlite3` for some paths) — call the
  141. `capabilities` tool for live status and install hints.
  142. Unlike the Python server, this one has Node dependencies. `npx davinci-resolve-mcp setup` installs them
  143. into the managed install (`npm install --omit=dev --omit=optional` under `resolve-advanced/`) and only
  144. then registers the bin. If that install could not run — offline, or npm unavailable — setup registers
  145. an `npx` command for the advanced server instead, so the entry it writes always boots. To repair an
  146. existing install without re-running setup: `npx davinci-resolve-mcp sync`.
  147. ### Bradford Post Assistant — managed application (closed beta)
  148. The maintainers also build **Bradford Post Assistant**, a desktop application on top of this
  149. open foundation. Where the MCP servers give an agent hands, Post Assistant is the working
  150. copilot around them — an on-device AI assistant for post-production where client material
  151. never leaves the workstation:
  152. - **A post-production copilot** — a desktop app that sits alongside DaVinci Resolve and
  153. watches the session live (timeline, grades, and frames — not just API calls), with an
  154. embedded AI assistant and agent runtime, local media analysis (transcription, frame
  155. analysis, editorial intelligence), and in-app conform QC.
  156. - **Memory** — persistent, encrypted on-device assistant memory plus cross-episode learning
  157. mined from your pipeline's decoded facts (season-look drift, per-camera correction priors,
  158. hero-frame libraries, conform path-map reuse), with accumulation managed for you and a
  159. reviewed-insight workflow.
  160. - **Self-contained by design** — Post Assistant wires everything itself: this MCP for
  161. Resolve control, the Bradford API for its extended services, and your choice of LLM
  162. provider. Nothing to configure by hand, no separate clients to manage, and the app keeps
  163. itself (and its bundled MCP) current with signed auto-updates.
  164. - **An extended professional toolset** — grade surgery on live projects, 22+ adaptive grade
  165. families, a curated looks library, delivery-spec validation, editorial pacing/cleanup
  166. analysis, natural-language color direction, and Fusion composition authoring — delivered
  167. through the managed Bradford API.
  168. - **Production workflows** — the raw tools composed into finished, real-world flows
  169. (turnover → conform → QC → delivery, season-look carry, episode reporting) with the
  170. guardrails and approvals a client-facing shop expects.
  171. It is currently in **closed beta** — you can request access at
  172. [bradfordoperations.com/software/post-assistant](https://www.bradfordoperations.com/software/post-assistant).
  173. The open-source servers are complete and fully functional on their own.
  174. ## What You Can Do
  175. For scoring to picture, the [Resolve / Live film workflow](docs/guides/film-workflow.md)
  176. adds picture/cue baselines, change reports, verified new-track stem return and
  177. evidence-based handoff preflight. It preserves source media and reports missing
  178. calibration or delivery evidence explicitly.
  179. ```text
  180. "List all projects and open the one called 'My Film'"
  181. "Create a timeline called 'Assembly Cut' from all clips in the current bin"
  182. "Build a multicam prep timeline from selected camera angles and preserve source media"
  183. "Detect 2-pops or slate claps and suggest record offsets for sync prep"
  184. "Publish analysis summaries, keywords, people, and slate hints into Resolve clip metadata"
  185. "Probe this timeline for gaps, overlaps, missing media, and source frame ranges"
  186. "Safely import this image sequence, organize it into bins, and normalize clip metadata"
  187. "Build a ProRes 422 HQ render plan, validate the settings, and queue the job"
  188. "Copy review markers from the timeline to the selected clip and export a review report"
  189. "Snapshot this clip's grade, validate a CDL update, and export a temp LUT"
  190. "Create a Fusion TextPlus overlay on the selected clip and verify graph connections"
  191. "Report audio channel mappings, voice isolation availability, and subtitle support"
  192. "Install this MCP-marked DCTL or script, classify refresh/restart needs, then remove it"
  193. ```
  194. ## Core Capabilities
  195. | Area | What the compound server supports |
  196. |------|-----------------------------------|
  197. | App and project control | Launch/reconnect, page switching, project CRUD, project folders, databases, cloud project wrappers, settings, presets, archives |
  198. | Media pool and ingest | Safe import, image sequences, multicam prep timelines, bin organization, metadata normalization, metadata field inventory, marks, annotations, relink/proxy/full-resolution guards |
  199. | Media analysis | Source-safe file/clip/bin/project analysis, 2-pop/slate-clap sync-event detection, default Resolve metadata and Media Pool marker writeback, persisted analysis artifacts, existing-report reuse, host_chat_paths visual analysis (finalized per clip with `commit_vision`, works with any vision-capable MCP client) with opt-out, transcription with opt-out |
  200. | Timeline editing and conform | Track/item probing, title text key scans/writes, copy/move/duplicate helpers, ripple insert, range operations, gaps/overlaps, source ranges, checked interchange exports/imports |
  201. | Review annotations | Timeline/item/clip markers, custom data, flags, clip color, copy/move/sync cleanup, review reports, marker thumbnail review |
  202. | Color and grading | Node graph probing, CDL validation, grade copy, DRX/LUT helpers, versions, Gallery stills, color groups |
  203. | Fusion | Timeline-item comps, safe tool creation, input writes, port inspection, validated connections, scoped bulk writes |
  204. | Audio and Fairlight | Track/item probes, source mapping, guarded audio property writes, voice isolation, auto-sync planning, transcription/subtitle probes |
  205. | Render and deliver | Format/codec matrix probing, render settings validation, queued job lifecycle checks, guarded Quick Export |
  206. | Extension authoring | Fuse, DCTL, ACES DCTL, and Resolve-page Lua/Python script lifecycle helpers with safe MCP-marked install/remove |
  207. | Craft guidance | The bundled editorial, colour, audio, and workflow guidance served as prose over MCP — indexed, searchable, and readable by any client, not just ones with this repository on disk |
  208. ### Operation envelope
  209. Every compound tool return carries an `_operation` block beside its payload, so
  210. an agent reads one shape instead of a different key per tool: `status`
  211. (`success` / `partial` / `blocked` / `failed`), `verification` (with
  212. `contradiction` kept distinct — Resolve reported success and the readback
  213. disagreed), `changes` (the semantic delta), `warnings`, and an `execution_id`.
  214. Two absences are meaningful and deliberate. `verification.status: "unverified"`
  215. means *no evidence was reported*, not "checked and clean". A missing `changes`
  216. means the action did not report a delta, not that nothing changed — an empty
  217. `{}` there would be a confident, wrong answer about an edit that simply never
  218. declared one.
  219. The envelope is namespaced rather than merged into the top level because
  220. `status`, `operation`, `warnings`, `result` and `changes` are all already domain
  221. keys here; flattening would rewrite a background job's `status: "done"` and a
  222. confirm gate's `status: "confirmation_required"`. `setup(action="set_defaults",
  223. params={"result_envelope": "pure" | "legacy"})` changes the shape, per call via
  224. `params={"envelope": ...}`, per process via `RESOLVE_MCP_RESULT_ENVELOPE`.
  225. ### Agent execution traces ("Why did the editor do this?")
  226. Multi-step AI operations correlate across tool calls into unified execution
  227. traces. Each trace aggregates tool durations (`duration_ms`), call counts, cumulative
  228. semantic deltas (`items_deleted`, `items_added`), and readback verifications.
  229. Agents and editors can inspect workflows via `resolve_control`:
  230. `get_execution_trace(execution_id?)`, `list_recent_executions()`, or open a
  231. scoped execution with `begin_execution(request="...")` / `end_execution()`.
  232. `export_execution_report(execution_id?, format="markdown"|"json")` writes a
  233. reviewable audit artifact with the same summary, defaulting to
  234. `logs/execution-reports/<execution_id>.md`. `path` writes it anywhere you want
  235. it instead — alongside a conform in a dated TransferFiles folder, say — and
  236. creates the directories to get there, so check the path before you send it.
  237. An existing file is never replaced without `overwrite: true`.
  238. `inspect_operation(tool?, target_action?, target_params?)` evaluates pre-flight
  239. risk level (`low`, `medium`, `high`, `critical`), destructive potential, and blast
  240. radius (`item`, `track`, `timeline`, `project`, `system`) before taking action, while
  241. `list_lifecycle_hooks()` inspects active execution interceptors.
  242. It is a heuristic over action names, not a simulation — it never touches the
  243. project and does not validate your parameters, so `recognised: false` means the
  244. levels are defaults rather than a finding, and `snapshot_available: null` means
  245. rollback availability was not determined rather than absent. Every shipped hook
  246. observes; none replaces a tool's result, so `dry_run` always reaches the real
  247. handler and nothing synthesises a preview for an action that has none.
  248. A report for a run where nothing was verified says **"not established — no
  249. checks recorded"**, not "passed". Absence of evidence is a question still open,
  250. and an audit document is the last place to let a reader read it as an all-clear.
  251. Traces live in a 100-entry in-memory ring and are appended to
  252. `logs/execution-traces.jsonl` beside `server.log` — `RESOLVE_MCP_TRACE_FILE`
  253. moves it, and `RESOLVE_MCP_LOG_FILE` moves `server.log` itself (a path, or empty
  254. for no file; the offline test suite points it at a temporary file so it never
  255. writes into the operator's log). `list_recent_executions` reports that path and whether it is
  256. writable, so "the log is empty" and "nothing is being written" are
  257. distinguishable without reading the source. What is recorded is tool name,
  258. action, timing, status, semantic deltas and verification — no parameters and no
  259. file paths. The one free-text field is the `request` you pass to
  260. `begin_execution`, so treat it the way you would a commit message on a client
  261. project.
  262. ## Verified-Trap Guard
  263. `src/utils/api_truth.py` records behaviours of the Resolve API that were measured
  264. against a live build rather than read off a signature — calls that return `True`
  265. having done nothing, settings keys silently rejected, methods that are not there
  266. at all. That ledger used to be **pull-only**: it answered
  267. `resolve_control(action="api_truth")` and was otherwise a file nobody greps in
  268. the middle of a job.
  269. It now reaches the caller at the callsite. An action mapped to a symbol with a
  270. recorded fact carries a compact `known_limitation` on its result — symbol,
  271. reality, recommendation, and nothing else, because response weight is a real cost
  272. on a long grading session and the full entry is one lookup away.
  273. A fact is only attached when the mapping names that exact symbol. Nothing is
  274. inferred from a similar name: an unrelated explanation stapled to a failure reads
  275. as a diagnosis, and a wrong diagnosis is worse than none.
  276. **One behaviour refuses rather than warns.** `TimelineItem.CopyGrades` replaces
  277. the target's grade wholesale — measured by baking each state to a 33-point LUT
  278. and comparing bytes — returns `True` while doing it, and creates no version to go
  279. back to. Applied to clips carrying hand-work, that is unrecoverable loss reported
  280. as success. So actions that call it refuse until the caller passes
  281. `acknowledge_trap: true`:
  282. ```json
  283. {
  284. "success": false,
  285. "error": "'timeline_item_color.copy_grades' is refused: its verified behaviour destroys existing work that cannot be recovered afterwards.",
  286. "known_limitation": [{"symbol": "TimelineItem.CopyGrades", "reality": "...", "recommended": "..."}],
  287. "retry_with": {"acknowledge_trap": true}
  288. }
  289. ```
  290. The intent is not to forbid the operation — it is to make the caller say out loud
  291. that they know what it does. Dry runs are exempt: a preview destroys nothing.
  292. Set `RESOLVE_MCP_DISABLE_TRAP_GUARD=1` to turn both the refusal and the advisory
  293. push off. This is a behaviour change for callers that previously received a bare
  294. `{"success": true}` from a destructive copy.
  295. Facts that power a refusal must stay re-measurable, so a live probe re-derives
  296. each one and records `drifted` when Resolve stops agreeing; a test fails if a
  297. `destroys_prior_work` entry has no probe.
  298. ## Optional Extras
  299. The core install is deliberately small: Python, ffmpeg, and the Resolve scripting
  300. API. Some features need more, and **each one refuses honestly with its own
  301. install line rather than degrading into a guess** — a fabricated tempo or an
  302. invented level produces confident, wrong output, which is worse than no feature.
  303. Run `python scripts/doctor.py` to see which of these you have.
  304. | Extra | Unlocks | Licence |
  305. |---|---|---|
  306. | **ffmpeg** on PATH | Silence detection, dead-space markers, level measurement, audio analysis. The single most useful thing to install. | LGPL/GPL — invoked as a subprocess, never bundled |
  307. | `pip install numpy` | Colour pre-balance, reference-still matching, sound-density audit | BSD |
  308. | `pip install librosa` | Beat, bar and phrase detection for music-driven cutting | ISC |
  309. | `pip install -U openai-whisper` | Transcription, and everything word-level built on it | MIT |
  310. | `pip install open_clip_torch` | Visual similarity and `find_similar` | MIT |
  311. | `pip install transformers` | CLAP audio embeddings | Apache-2.0 |
  312. | `pip install opencv-python` | Additional frame analysis | Apache-2.0 |
  313. `media_analysis` action `capabilities` reports the analysis stack in detail and
  314. tells you what each missing piece would enable.
  315. **Nothing here is bundled.** Model weights carry their own licences separate from
  316. the code that loads them; check them before commercial use.
  317. ## What This Does Not Do
  318. Knowing where a tool stops is worth as much as knowing what it does, and it is
  319. cheaper to read it here than to discover it mid-project.
  320. | Not supported | Why, and what you get instead |
  321. |---|---|
  322. | **Choosing the best take** | Performance is most of what makes a take right, and none of it is measurable from a waveform or a transcript. `rank_takes` ranks *fluency* — fillers, restarts, script coverage — and says so in every response. The take that plays is regularly the least fluent one, because the hesitation is often the acting. Use it to find the clean safety take, not to choose the read. |
  323. | **Automatic music editing** | Optional `librosa` support provides beat detection and beat/bar/phrase cut-point plans, not a finished assembly. Downbeats are inferred from the first beat; use `beat_offset` for pickups. Speech-silence tools are unsuitable for finding musical edit points. |
  324. | **Judging a cut** | Nothing here has an opinion about whether an edit is good. Every destructive action is plan → review → confirm for that reason. |
  325. | **Replacing an editor** | The output is a first-pass assembly, in the assistant-editor sense: ingest, sync, organize, string out, flag problems. It is a starting point you cut, not a finished cut. Defaults are deliberately **generous** — a first assembly is supposed to run long, because trimming is fast and visible while recovering discarded material is slow and invisible. |
  326. | **Modifying your source media** | By design and without exception — see below. |
  327. Anything analyzed but unverifiable is reported as unverified, never folded into
  328. "fine". An empty result means "nothing found", never "nothing to find".
  329. ## Source Media Safety
  330. This project treats camera originals and source media as immutable. Analysis tools read source files and write reports only to sidecar, scratch, or project analysis directories; confirmed metadata publishing writes only to Resolve's project database. The server must not modify, transcode, proxy, or create derivatives of source media unless the user explicitly asks for that. See [Media Analysis Guide](docs/guides/media-analysis-guide.md) for the detailed source-safe workflow.
  331. ## Security Posture
  332. The default server is a local stdio process launched by your MCP client; it does not expose a network listener or built-in multi-user auth surface. The two opt-in local HTTP surfaces — the control panel and the networked MCP transport — bind loopback only and require a per-launch bearer token on every request, with Host/Origin checks against DNS rebinding and CSRF. Tool metadata includes MCP client-safety hints for read-only, destructive, idempotent, and external-resource operations. Destructive writes on both servers honour `destructive.safe_mode` and the security audit log; only the compound server archives a timeline before mutating it — granular writes are refused or recorded, never recovered. See [Security Policy](SECURITY.md) for operational boundaries, confirmation guidance, and vulnerability reporting.
  333. ## Key Stats
  334. | Metric | Value |
  335. |--------|-------|
  336. | MCP Tools | **37** compound / **390** granular (live server) |
  337. | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
  338. | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
  339. | API Methods Covered | **361/361** (100%) |
  340. | Methods Live Tested | **349/361** (96.7%) |
  341. | Live Test Pass Rate | **349/349** (100%) |
  342. | Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio + Resolve 21.0.3 and 21.0.4 **free** (via the in-app bridge) |
  343. For method-by-method status, see [API Coverage and Test Results](docs/reference/api-coverage.md). For current workflow support, see [Kernel Action Coverage](docs/kernels/README.md).
  344. `analyze_media` executes directly by default, persists inspectable reports/artifacts under the analysis root, requests host-chat visual analysis via the `host_chat_paths` protocol (analyze returns absolute frame paths + a JSON schema; the host chat reads each frame as an image and calls `media_analysis(action="commit_vision", ...)` to finalize), runs transcription through the configured local backend, and writes analysis summaries plus source-time Media Pool clip markers back to the Resolve project. Pass `include_visuals=false`, `include_transcription=false`, `publish_metadata=false`, `timed_markers=no`, or `dry_run=true` only when you want to opt out of those default behaviors. Skipping `commit_vision` leaves the run in `pending_host_vision_analysis` — surfaced as a failure mode, not silently downgraded.
  345. ## Documentation
  346. | Document | Use it for |
  347. |----------|------------|
  348. | [Installation and Configuration](docs/install.md) | Requirements, installer options, supported clients, server modes, manual config |
  349. | [API Coverage and Test Results](docs/reference/api-coverage.md) | Key stats, API coverage table, live-test status, full method reference |
  350. | [Kernel Action Coverage](docs/kernels/README.md) | Current guarded workflow action map |
  351. | [AI Skill Reference](docs/SKILL.md) | Operational context for AI assistants using the compound server |
  352. | [Control Panel Guide](docs/guides/control-panel.md) | Local browser panel tour: Overview, Review (bin/clip/shot), Analyze, Setup, Preferences |
  353. | [Media Analysis Guide](docs/guides/media-analysis-guide.md) | Source-safe FFprobe, FFmpeg, Whisper, sidecar, and analysis-root workflows |
  354. | [Multicam Setup Helper Guide](docs/guides/multicam-setup-guide.md) | Stacked timeline prep, helper/API boundary, and Resolve UI conversion steps |
  355. | [Editorial Decision Guide](docs/guides/editorial-decision-guide.md) | Project-owned editorial craft guidance for analysis and timeline decisions |
  356. | [Conforming an Avid AAF](docs/guides/conforming-an-avid-aaf.md) | Why all three Resolve-native routes fail on a consolidated turnover, and which one is dangerous |
  357. | [Native .drt Authoring](docs/guides/native-drt-authoring.md) | Offline template-spliced timeline authoring: cuts, retimes, transitions, fades, markers, compounds — and the measured laws behind them |
  358. | [Headless Edit Loop](docs/guides/headless-edit-loop.md) | Driving Resolve from the command line: which interchange formats relink and round-trip, measured in GUI and -nogui |
  359. | [Color Decision Guide](docs/guides/color-decision-guide.md) | Project-owned color correction guidance and Resolve color API boundaries |
  360. | [Contributing and Project Layout](docs/contributing.md) | Contribution workflow, platform support, security notes, repository structure |
  361. | [Security Policy](SECURITY.md) | Local stdio trust boundary, tool metadata, confirmation guidance, reporting |
  362. | [Release Process](docs/process/release-process.md) | Maintainer release checklist, version surfaces, validation, tags, and release notes |
  363. | [Changelog](CHANGELOG.md) | Historical release notes |
  364. Extension authoring references live in [docs/authoring](docs/authoring/). Resolve developer-package notes live in [docs/notes](docs/notes/) and [docs/integrations](docs/integrations/). Prompt recipes live in [examples](examples/).
  365. ## Requirements
  366. - 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](#free-edition-in-app-bridge), which runs inside Resolve from the ungated **Workspace ▸ Scripts** menu.
  367. - 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.
  368. - Not connecting? `python3 scripts/doctor.py` checks the Python the server runs on and prints the exact fix for each problem: 32-bit or wrong-architecture Python, a Python too new for your Resolve build, or several Pythons where the MCP client starts the wrong one. See [Checking the Python environment](docs/install.md#checking-the-python-environment).
  369. - Resolve external scripting set to **Local** (Studio). On the free edition this
  370. preference has no effect — use the [in-app bridge](#free-edition-in-app-bridge)
  371. instead.
  372. 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](docs/reference/api-coverage.md#resolve-21-delta-detail). 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.
  373. ## Reporting Bugs and Requesting Features
  374. Tell your assistant "send this as a bug" or "send this as a feature request". It
  375. drafts a GitHub issue from the conversation, including the failing call and
  376. its error, and attaches the server version, Resolve build, connection mode and
  377. OS. Local paths, your username and anything that looks like a secret are
  378. redacted. Nothing is filed for you: you get a prefilled link, review the
  379. draft, and submit it on GitHub yourself. You can also
  380. [open an issue](https://github.com/samuelgursky/davinci-resolve-mcp/issues/new/choose)
  381. directly.
  382. ## Development
  383. ```bash
  384. python src/server.py # Compound server
  385. python src/server.py --full # Granular server
  386. venv/bin/python tests/test_import.py
  387. venv/bin/python scripts/audit_api_parity.py
  388. ```
  389. Release and validation rules are in [docs/process/release-process.md](docs/process/release-process.md). AI agents working in this repository should start with [AGENTS.md](AGENTS.md); Claude Code users can also read [CLAUDE.md](CLAUDE.md), which points to the same canonical instructions.
  390. ## License
  391. MIT
  392. ## Author
  393. Samuel Gursky (samgursky@gmail.com)
  394. - GitHub: [github.com/samuelgursky](https://github.com/samuelgursky)
  395. ## Acknowledgments
  396. - Blackmagic Design for DaVinci Resolve and its scripting API
  397. - The Model Context Protocol team for enabling AI assistant integration

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.