resolve-mcp

An MCP server that gives an AI assistant control of DaVinci Resolve Studio on macOS.

132 tools across projects, media, timelines, colour, rendering and Fusion — plus resolve_exec for anything the curated tools miss, and resolve_ui for the handful of operations Blackmagic never exposed to scripting at all.

"Import this folder, build a timeline in filename order, add a marker at every
 scene cut, then queue ProRes and H.264 renders and tell me when they're done."

Install

Requires macOS, DaVinci Resolve Studio (external scripting is a Studio feature), Python 3.13+ and uv.

git clone https://github.com/irstone-source/resolve-mcp.git
cd resolve-mcp
uv sync
uv run python scripts/smoke.py     # verify the connection before wiring anything up

Then register with Claude Code:

claude mcp add resolve -- uv run --directory /absolute/path/to/resolve-mcp resolve-mcp

One manual step, once. In Resolve: Preferences → System → General → External scripting using: Local. No API can set it, and without it nothing works. Full detail in docs/SETUP.md.

Documentation

Setup	Requirements, permissions, headless mode
Tool reference	All 132 tools and 6 resources, generated from the server
Architecture	How it works and why it's built this way
Troubleshooting	Failure modes and Resolve's undocumented behaviour
Development	Adding tools, testing, conventions

How to drive it

Reach for capabilities in this order:

1. A curated tool — project_*, media_*, timeline_*, track_*, marker_*, clip_*, lut_*, render_*, fusion_*. Typed, validated, with actionable errors.
2. resolve_exec — arbitrary Python against the live connection, for the long tail of the API. The installed scripting reference is served as MCP resources, so calls are written against real signatures rather than recalled ones.
3. resolve_ui — AppleScript menu clicks and keystrokes. Only where no API exists.

Handles

Resolve returns live objects that can't be sent as JSON, so clips, timeline items, folders and stills pass between calls as handles:

clip:1a2b3c      a media pool clip
item:0091        a clip on a timeline
folder:root      a bin
timeline:4f2a    a timeline
still:2b70       a gallery still

Objects returned by resolve_exec get handles too, so escape-hatch code composes with the curated tools.

Every tool returns the same envelope

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "No timeline is currently open",
                "hint":  "Create a timeline with timeline_create, or select one with timeline_set_current." }

The Resolve API signals failure by returning bare False or None with no explanation. This server converts each known cause into a named condition with a remedy, so a failed call tells you what to do next instead of merely that something went wrong.

What it's good at

Repetitive and generative work: batch operations across many clips or timelines, conforming, marker-driven assembly, and querying an edit as data. It reads a timeline as structured information — every clip with its in/out, duration, track position and metadata.

What it can't do is exercise visual judgement. It sees metadata, not pictures, unless you ask it to render a still and look at one.

Notable behaviour it works around

• scriptapp() blocks forever when Resolve is running but refuses a connection — inside C, without releasing the GIL, so no signal or thread timeout recovers it. Every connection is probed in a killable subprocess first.
• AddRenderJob returns '', not False, when it declines — so an empty job id would otherwise be handed back as success.
• Resolve's dialogs are invisible to macOS Accessibility (they're Qt-drawn), and a modal blocks scripting while open. Tools validate inputs client-side rather than provoking one.
• Unknown render setting keys are silently ignored, making a typo look like success. Keys are validated against the installed reference.

More in docs/TROUBLESHOOTING.md.

Development

uv run pytest                 # 195 unit tests, no Resolve needed
uv run pytest -m live         # integration suite against real Resolve
uv run ruff check . && uv run ruff format .

Unit tests run against an in-memory double shaped like the real API, so the suite needs no Resolve installation and no application state to reset. The live suite works inside a throwaway MCP_TEST_<pid> project and restores whatever project was open.

Status

Verified against DaVinci Resolve Studio 21.0.2.4 on macOS. 195 unit tests and 13 live integration tests passing.

Licence

MIT — see LICENSE.

Not affiliated with or endorsed by Blackmagic Design. DaVinci Resolve is a trademark of Blackmagic Design Pty Ltd.