DaVinci Resolve MCP

A 64-tool stdio MCP server for DaVinci Resolve’s documented scripting API. Windows 11 is the primary platform, macOS is supported, and Linux support is best effort. The project does not use UI automation, OCR, simulated input, or undocumented Resolve methods.

Windows Quick Start

Requirements: Windows 11, Python 3.12 or newer, Git, and DaVinci Resolve. Live external control may require Resolve Studio, depending on the installed edition and Blackmagic’s scripting support.

Use a writable source location—not Program Files:

cd "$env:USERPROFILE\Documents\GitHub"
git clone https://github.com/BillyRaz/Davinci-MCP.git
cd Davinci-MCP
.\setup-davinci-mcp.ps1

Setup prefers py -3.12, falls back to a compatible python, creates .venv, installs .[dev], generates the user config, and runs pytest, Ruff, and offline validation. It never installs packages silently, requests Administrator access, or changes execution policy globally.

Run and validate:

.\run-davinci-mcp.ps1
.\validate-davinci-mcp.ps1
.\validate-davinci-mcp.ps1 -Live

The .cmd wrappers provide equivalent double-click entry points. The live option is read-only and should only be used with Resolve Studio open. Resolve Free external scripting limitations are reported as warnings/unsupported capability, not MCP defects.

The parameterized global color-treatment LUT engine is documented in docs/LUT_ENGINE.md.

To create an optional Desktop shortcut:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\create_windows_shortcut.ps1

The script only creates Run DaVinci MCP.lnk; it does not alter security settings.

Related MCP server: DaVinci Resolve MCP Server

Windows Codex and MCP Configuration

Keep executable and argument as separate values. Replace the example clone path:

{
  "mcpServers": {
    "davinci-resolve": {
      "command": "C:\\Users\\YOUR_NAME\\Documents\\GitHub\\Davinci-MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YOUR_NAME\\Documents\\GitHub\\Davinci-MCP\\server.py"
      ]
    }
  }
}

For Codex, add the server to the MCP configuration used by your Codex installation; inspect and preserve existing servers before editing it. Generic stdio and VS Code-compatible clients can use the same command/args object.

Windows troubleshooting:

• “Missing .venv”: run .\setup-davinci-mcp.ps1.

• Python not found: install Python 3.12+ with the py launcher, then reopen the shell.

• Resolve connection unavailable: open Resolve Studio and enable local External scripting in Resolve Preferences. Do not change preferences automatically.

• Permission errors: clone under Documents or Developer, not Program Files.

• Paths are discovered from ProgramFiles, ProgramData, APPDATA, LOCALAPPDATA, and USERPROFILE; explicit environment overrides take priority.

macOS Installation

Clone into a user-owned development directory, then use the portable launchers:

mkdir -p "$HOME/Developer"
cd "$HOME/Developer"
git clone https://github.com/BillyRaz/Davinci-MCP.git
cd Davinci-MCP
./setup-davinci-mcp.command
./run-davinci-mcp.command

Apple Silicon and Intel are detected automatically. The launcher retains Blackmagic’s official scripting locations:

export RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting"
export RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so"
export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}$RESOLVE_SCRIPT_API/Modules"

RESOLVE_SCRIPT_API accepts either the parent Scripting directory or its direct Modules directory. A generic/Codex macOS configuration is:

{
  "mcpServers": {
    "davinci-resolve": {
      "command": "/Users/YOUR_NAME/Developer/Davinci-MCP/.venv/bin/python",
      "args": ["/Users/YOUR_NAME/Developer/Davinci-MCP/server.py"]
    }
  }
}

Linux Installation (Best Effort)

Linux discovery checks /opt/resolve, /opt/resolve/Developer/Scripting, and common libraries under /opt/resolve/libs, while honoring all overrides:

./setup-davinci-mcp.sh
./run-davinci-mcp.sh
./validate-davinci-mcp.sh

Linux paths and launchers are mock-tested, but live Resolve behavior is not claimed as fully validated.

Capture Support

Capture tools export genuine Resolve output only:

• capture_current_frame

• capture_clip_reference

• capture_before_after_reference

• list_captured_references

• open_capture_folder

• delete_captured_reference

Capture uses documented current-frame export when exposed, Gallery still export/delete as a fallback, or a supported temporary one-frame render path. Pillow is used only to combine already-exported images or calculate technical image-change metrics. A “before” is never claimed unless it was actually captured first.

Every generated file result includes its absolute path. Metadata includes the project, timeline, frame/timecode, timestamp, and actual capture method.

TimelineItem Locks

The playhead is an acquisition tool only. lock_timeline_item (and the compatible lock_timeline_target name) double-reads the item under the playhead, validates any confirmed identity, and stores a session-local TimelineItemLock. The stored lock contains project, timeline, item unique ID, original track/address and frame range, duration, source identity/path, creation time, and connection generation. It does not contain the playhead position.

All production capture and grading tools re-resolve the locked item by Resolve unique ID before acting and use its currently resolved track/item address. Moving the playhead, playing, scrubbing, or switching Resolve pages therefore does not invalidate the lock. A project or timeline switch, connection generation change, missing or ambiguous item, explicit release, or server restart does.

queue_timeline_item supports acquiring multiple independent item identities for future batch workflows. validate_queued_timeline_items resolves the queue without consulting the playhead. Queue entries are session-local and are not persisted.

The official API does not expose timeline-item selection independently of the playhead, so initial interactive acquisition still uses the item under it. Capture may temporarily move the timeline to export an explicit frame and then restore the editor's timecode; this does not change which TimelineItem is locked.

Validation

Offline validation checks Python, dependencies, platform discovery, scripting paths, native library, writable output, config, presets, and MCP registration. Live validation additionally inspects the read-only connection/project/timeline/ clip/Gallery/render capabilities. It does not apply grades, start renders, or change the active timeline.

Reports use passed, warning, failed, skipped, and unsupported, and are written as JSON and Markdown with timestamped copies.

Configuration and Output Paths

Default config:

Default output root:

Each root contains captures, comparisons, validation, logs, reports, presets, and cache.

Older macOS artifacts at /Applications/DaVinci Resolve/davinci-mcp/output are left untouched. Copy wanted files manually into the new Application Support subdirectories; no automatic move or deletion occurs.

Environment variables override TOML configuration:

• DAVINCI_RESOLVE_HOME

• RESOLVE_SCRIPT_API

• RESOLVE_SCRIPT_LIB

• DAVINCI_MCP_OUTPUT_DIR

• DAVINCI_MCP_PRESET_DIR

• DAVINCI_MCP_LOG_LEVEL

• DAVINCI_MCP_CONNECTION_MODE

• DAVINCI_MCP_CAPTURE_FORMAT

• DAVINCI_MCP_TEMP_RENDER_DIR

• DAVINCI_MCP_CONNECTION_TIMEOUT

• DAVINCI_MCP_RENDER_TIMEOUT

Discovery priority is explicit override, existing discovered installation, known platform default, then a clear validation failure when the selected path is absent.

Development and Testing

python3.12 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
.venv/bin/python scripts/offline_validate.py

On Windows, replace .venv/bin/python with .venv\Scripts\python.exe. GitHub Actions runs Python 3.12 tests and Ruff on Windows, macOS, and Ubuntu without attempting a live Resolve connection.