Docs

DaVinci Resolve MCP Server — AI Skill Reference

This document gives AI assistants the context needed to use the DaVinci Resolve MCP server effectively. It covers the tool landscape, page prerequisites, common workflow patterns, error recovery, and known gotchas.

---

What This Server Does

The DaVinci Resolve MCP server bridges AI assistants to DaVinci Resolve Studio via its official Scripting API. You can control every aspect of a post-production session — projects, timelines, clips, color grading, Fusion compositions, audio, render queues, and more — through natural language.

DaVinci Resolve must be running with Preferences > General > "External scripting using" set to Local. The server auto-launches Resolve if it is not running, but that first connection can take up to 60 seconds.

Workflow Integration plugins/scripts are a separate Resolve-hosted UI mechanism. They are not required for this MCP server, but docs/integrations/workflow-integrations.md summarizes when they are useful for optional in-Resolve panels, UIManager scripts, and render callback companions.

OpenFX plugins are native C++ image-effect plugins, not an MCP control surface. Use docs/notes/openfx-notes.md when diagnosing insert_ofx_generator failures or discussing optional OFX plugin development.

LUT files are directly relevant to Color-page graph actions. Use docs/notes/lut-notes.md when diagnosing graph.set_lut failures, validating .cube files, or explaining project_settings.refresh_luts.

Fusion templates are relevant to Edit/Cut page insertion actions. Use docs/notes/fusion-template-notes.md when diagnosing insert_fusion_generator or insert_fusion_title failures, template paths, .setting files, or .drfx bundles.

DCTL files are programmable color transforms/effects adjacent to LUT and OpenFX workflows. Use docs/notes/dctl-notes.md when diagnosing .dctl/.dctle discovery, ResolveFX DCTL plugin behavior, ACES DCTL IDT/ODT setup, or DCTL-as-LUT usage.

Codec plugins are native IO encode plugins that extend Deliver-page render formats/codecs. Use docs/notes/codec-plugin-notes.md when diagnosing missing custom render formats/codecs, .dvcp.bundle packaging, or IOPlugins install paths.

The fuse_plugin, dctl, and script_plugin compound tools (v2.5.0+) write Fuse plugin source, DCTL files, and Lua/Python scripts into Resolve's install directories. They are authoring tools — every other tool in this server wraps Resolve's scripting API, while these three emit and install plugin/script source. Status: lifecycle-verified in DaVinci Resolve Studio 20.3.2.9 for MCP-marked install/read/list/remove, regular DCTL refresh_luts, ACES/Fuse restart-required classification, Python installed-script execution, and Python/Lua run_inline. Use docs/kernels/extension-authoring-kernel.md for the kernel boundary map, docs/authoring/fuse-dctl-authoring.md for the Fuse + DCTL coverage matrix, and docs/authoring/script-plugin-authoring.md for the script DSL spec and the conversational-execution model. For hand-authoring .setting template files (Edit effects/transitions/titles/generators and Fusion macros) — the format, control catalog, thumbnail conventions, install paths, and gotchas, plus copyable starter templates — see docs/authoring/setting-files/.

Extension Authoring kernel actions (v2.16.0+) are exposed through script_plugin:

• extension_capabilities
• probe_fuse_lifecycle(name?, kind?, install?, cleanup?)
• probe_dctl_lifecycle(name?, kind?, category?, install?, refresh_luts?, cleanup?)
• probe_script_lifecycle(name?, language?, category?, install?, execute?, cleanup?)
• safe_install_extension(extension_type, name, source?|kind?, dry_run?)
• safe_remove_extension(extension_type, name, dry_run?)
• refresh_or_restart_required(extension_type, category?)
• extension_boundary_report(include_template_matrix?)

Key behavioral notes for script_plugin:

• run_inline(source, language) runs ad-hoc Lua/Python in Resolve and returns

stdout + result — use this for one-off conversational queries against the Resolve API instead of building+installing a script.

• language accepts lua, py, or the human-facing aliases python and

python3.

• execute(name, category, language) runs an installed script; Python stdout

and stderr are captured, while installed Lua execution can return false from the Python bridge even when install/read/list/remove worked.

• Lua scripts: fusion.Execute() from the Python bridge is a no-op in

Resolve 20.x — _run_inline_lua works around this with RunScript against a temp file plus completion-sentinel polling on app:SetData/GetData.

• Fuse install path on macOS is …/DaVinci Resolve/Fusion/Fuses/ (NOT

Support/Fusion/Fuses/ as the SDK doc lists). The MCP path helpers handle this; if you're staging files manually, use the path the implementation emits.

• Resolve picks up new scripts without a restart; new Fuses need a restart

to register; new DCTLs need project_settings(action='refresh_luts') (regular LUT category) or a restart (ACES IDT/ODT category).

Tool metadata (v2.17.1+) includes MCP ToolAnnotations for read-only, destructive, idempotent, and external-resource hints. Treat compound tool annotations as conservative because a single compound tool may expose both probe and mutation actions behind its action parameter. Continue to prefer safe_*, dry_run, probe_*, capabilities, and boundary_report actions before mutating Resolve state.

---

Two Server Modes

| Mode | Entry point | Tool count | Use when | |---|---|---|---| | Compound (default) | src/server.py | 32 tools | Most workflows — keeps context lean | | Granular (full) | src/server.py --full | 341 tools | Power users needing one tool per API method |

This skill document covers the compound server (the default). Each compound tool accepts an action string and an optional params object.

The compound server also registers MCP prompts. Use davinci_resolve_workflow as the compact operating brief, and use analyze_media as a slash-command style entry point for source-safe project, selected-clip, bin, file, or sequence analysis. The Analyze Media prompt executes directly by default, persists inspectable reports/artifacts under the project analysis root, requests host_chat_paths visual analysis (frames are extracted to disk and the host chat finalizes each clip via media_analysis(action="commit_vision", ...)), runs local transcription through the configured backend, and writes metadata plus source-time Media Pool markers back to the Resolve project unless the user opts out.

Anti-regression rule: do not silently downgrade media analysis. Source-safe means source media stays untouched; it does not mean no visuals, no transcript, no persisted report, no metadata writeback, or no Media Pool markers. Do not add include_visuals=false, include_transcription=false, publish_metadata=false, timed_markers=no, session_only=true, or dry_run=true unless the user explicitly asks for that opt-out, the target is a raw file path that cannot receive Resolve project writeback. The hostchatpaths vision protocol is: analyze_* returns a deferred payload with absolute frame_paths and a JSON schema; you must read those frames as images (Claude Code's Read tool handles JPG/PNG natively), produce the JSON, and call commit_vision for each clip. Skipping commit_vision leaves the run in pending_host_vision_analysis — surface that explicitly; do not call the analysis complete.

The deferred payload also includes a host_tool_choice_hint block. Hosts that respect this hint pass it as tool_choice={type:"tool", name:"media_analysis"} on the next API turn, hard-locking the agent into the correct next call. Hosts that don't recognize the field ignore it — the flow is unchanged for them.

Local Control Panel

If the user asks to open, launch, or inspect the Resolve MCP control panel, run this from the repository root:

venv/bin/python -m src.control_panel

The command starts the local control panel and opens the default browser. Use --no-open when running in a headless context, then give the user the printed localhost URL. The panel is local and single-user; it is an operational surface for server status, Resolve clips, source-safe analysis jobs, preferences, and diagnostics as those sections are added.

The Review tab → History button opens the timeline-history surface: per-timeline version chain, brain-edit deltas, manual archive, and rollback. Backed by timeline_versioning MCP actions; see that tool's section below for the underlying primitives.

---

Editorial Memory And Decision-Making

When the user asks for cutting, pacing, story shape, suspense, comedy timing, or tonal reframing, operate like an editor, not just a metadata scanner. Use docs/guides/editorial-decision-guide.md as the project-owned craft reference. The short version: emotion and story come first, then clarity, rhythm, eye trace, screen geography, continuity, and coverage variety.

Before analyzing or rebuilding anything, check whether the active project already contains useful evidence:

• media_analysis(action="coverage_report", params={"target": {...}}) — the

pre-flight contract. Pure read; never triggers analysis. Returns per-clip state (analyzed / stale / missing / reuseblocked / supersededby_relink), layer presence, source_trust tier, and a recommended_action. The response carries an evidence_base summary string — lead any editorial or color recommendation with that line, before the creative answer.

• media_analysis(action="summarize") for project-wide rollup of warnings,

motion distribution, and signed-report counts.

• media_analysis(action="get_report") when a manifest or report path is known.
• timeline(action="list")
• timeline(action="get_current")
• timeline(action="probe_timeline_structure")
• timeline(action="source_range_report")
• timeline_markers(action="get_all")
• media_analysis(action="review_timeline_markers") when marker imagery matters

Reuse prior analysis unless it is stale, incomplete, missing a modality, or flagged superseded_by_relink because Resolve's source clip was replaced after analysis ran. Coveragereport surfaces all of these in one read. Do not re-run visual analysis just because the edit task is new if a current report already has keyframes, motion variance, and usable visual descriptions. Add transcription, hostchatpaths vision (followed by commitvision), marker review, or source range checks only when that missing evidence changes the decision. Use force_refresh=true only when the user asks for a fresh read or when cache signatures show the source, prompt, depth, or requested modality has changed.

Source-trust filtering: coverage_report accepts min_source_trust (one of auto, filename, low, medium, high). Clips below the threshold appear in summary.clips_needs_higher_trust and are reported with below_min_source_trust=true. Use medium for routine work, high for shot-matching or look-development passes where confident scene/identity reads matter.

For finished-video editorial work, scene detection and motion variance are guardrails, not story. Use them to avoid black frames, flash frames, corrupt ranges, and accidental cut points. Let transcript, sound events, complete thoughts, reactions, and decisive visual frames drive the actual edit.

After creating or modifying a timeline variant, do a second pass before calling the work done:

• timeline(action="detect_gaps_overlaps")
• timeline(action="source_range_report")
• timeline_markers(action="get_thumbnail_image") at important markers and cuts
• Compare each marker name against the Resolve-rendered frame; revise the marker

or edit if the image contradicts the plan.

Do not depend on personal, external, or workstation-specific editorial context. For this project, keep the editorial craft reference self-contained in docs/guides/editorial-decision-guide.md and keep this SKILL.md focused on operational use of the MCP.

---

Color Memory And Decision-Making

When the user asks for color correction, shot matching, look development, LUTs, DCTLs, DRX grades, Gallery stills, or color-group workflows, use docs/guides/color-decision-guide.md as the project-owned color reference.

Be explicit about the API boundary:

• Directly creatable/control surfaces: CDL values on an existing node, grade

versions, color-group assignment, LUT assignment on existing nodes, node enable/cache state, LUT/DCTL assets, Gallery still import/export, and grade copy/export helpers.

• Opaque full-grade surfaces: copied grades, imported/exported .drx stills,

and manually built Resolve node graphs. These can carry full grades, but the MCP applies or copies them as packages.

• Not directly creatable from structured params: new node trees, Lift/Gamma/Gain

wheel values, log/HDR palette values, curves, qualifiers, power windows, tracking, Color Warper, and detailed ResolveFX/OFX parameter edits.

Before any color recommendation, run media_analysis(action="coverage_report", params={"target": {...}, "min_source_trust": "medium"}) (use "high" for shot-matching or look-development passes). Lead the response with the returned evidence_base line before the grade plan. Coverage_report surfaces relink-superseded clips that must be re-analyzed before being graded from prior visual descriptions.

For safe color work, start with timeline_item_color(action="grade_boundary_report"), timeline_item_color(action="grade_version_snapshot"), timeline_item_color(action="probe_node_graph"), and a Resolve-rendered frame reference for the target shot or shots. Use thumbnails, contact sheets, Gallery stills, marker frames, or existing visual analysis reports before writing a grade, and cite the inspected frames in the response. When the API can safely provide them, compare matched untreated/bypass, current, and after frames at the same timecodes, then restore the previous active version or node-enabled state after any temporary bypass capture. Treat untreated frames as diagnostic evidence, not as permission to discard an existing creative grade.

Prefer safe_set_cdl for small reversible primary corrections. Use DRX/stills or grade copy only when the user accepts whole-grade replacement/transfer semantics. Use DCTL/LUT authoring only for reusable mathematical transforms, not as a substitute for hand-built windows, qualifiers, or tracked secondaries. Do not apply blind/global grades unless the user explicitly asks for that. When the user asks to build on or adjust an existing grade, preserve the current grade/version as the starting point, create or switch to a recoverable adjustment version, and apply only incremental changes through supported controls. Do not reset grades, replace graphs, or apply DRX/copy-grade whole-grade artifacts unless replacement or transfer semantics are explicitly accepted. Distinguish Resolve's default one-node graph from an existing creative grade; only describe a creative grade when active tools, LUTs, or other grade state are present.

For sequence-wide looks, prefer a duplicated timeline, batch creation of reference/current/look versions across all target clips, and one bulk Resolve script for repeated version, group, or CDL operations. Use color groups for shared scene-level intent only when they fit the work: group pre-clip for shared normalization, clip versions for shot-specific matching, and group post-clip for the creative look. Sampling can guide a first pass, but final handoff should state the reviewed scope; short sequences should be checked shot by shot.

---

Page Context Requirements

DaVinci Resolve is a page-based application. Certain operations only work on specific pages. Always confirm or switch pages before calling page-sensitive tool

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hybridlabor-api
• Source: hybridlabor-api/bdb-dev-optimized-agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.