ResolveMCP-ext

resolve-ext

An MCP server that adds the DaVinci Resolve 21.1.2 scripting surfaces the mainstream Resolve MCP servers do not cover — clip effects, effect properties, Paste-Attributes, frame export and media-pool folder lookups.

It is deliberately an extension, not a replacement: register it alongside the other two Resolve MCP servers and you get a larger surface with no overlap — see the full setup. Everything it exposes is measured against a live Resolve, and calls that turn out to be broken are reported as broken rather than wrapped in a success.

effects              apply/list/remove/toggle/reorder clip effectsclip_attrs           copy attributes between clips (Paste Attributes)export_frame         stills from a clip or media-pool itemfolder_ops           which bin does this clip/folder live inphoto_albums         albums, photos, ratings, flags, versions, stillsnode_graph           node labels, colours, enable state, LUTs, cacheproject_extras       render presets, audio render formats, transcriptioncamera_comparison    2x2 / split layouts, camera labels, markersclip_position        read placement + handle offsets; flags broken APIsresolve_ext_status   health check

The full Resolve MCP setup — three servers, all of them

Resolve is not covered by one MCP server. Three independent servers do different jobs, and full coverage means running all three. This project is the third; the other two are not optional extras.

All three talk to the same Resolve through the same single-client scripting API. They coexist without overlap; registering one and wondering why a capability is missing is the usual disappointment.

# 1. Blackmagic's — already on disk, just register it:#    %ProgramFiles%\Blackmagic Design\DaVinci Resolve\ResolveMCP.exe   (Windows)#    /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Applications/ResolveMCP#    /opt/resolve/bin/ResolveMCP                                       (Linux)
# 2. the community server (use --clients manual when driving it non-interactively):npx davinci-resolve-mcp setup
# 3. this project:pip install https://github.com/CaptRauti/ResolveMCP-ext/releases/download/v1.0.0/resolve_ext-1.0.0-py3-none-any.whlresolve-ext doctor

Full procedure, per-platform paths, the Windows "Resolve is on another drive" case, and the failure modes of each: AGENTS.md — written so an AI agent can install all three unattended.

Why this exists

DaVinci Resolve 21.1.2 (22 Oct 2026) added a batch of scripting APIs. The popular MCP servers do not implement them — verified two ways: searching their source for each symbol, and probing live Resolve objects with hasattr (a type stub documents the API; only the live object proves your build has it).

TimelineItem alone exposes 113 methods on 21.1.2; a large share of them were unreachable through MCP before this server.

Install

Installing this with an AI agent? Point it at AGENTS.md — it is a step-by-step procedure written for agents, including the failure cases. This section is the human-facing version.

Requires Python 3.10+ and DaVinci Resolve Studio (external scripting is a Studio feature — the free build refuses it).

From a release (recommended)

Download the wheel from the releases page and install it:

pip install resolve_ext-1.0.0-py3-none-any.whl

The wheel is pure Python and platform-independent — the same file works on Windows, macOS and Linux.

From a git checkout

pip install git+https://github.com/CaptRauti/ResolveMCP-ext

Or from a local clone:

git clone https://github.com/CaptRauti/ResolveMCP-extcd ResolveMCP-extpip install .

mcp 2.x breaks FastMCP, so the dependency is pinned <2. That pin is in the package metadata — you do not need to add it yourself.

Verify the installation

resolve-ext doctor

resolve-ext 1.0.0
--- Python ---  3.12.4 at /usr/bin/python3  ok (3.10+)
--- DaVinci Resolve scripting API ---platform      linuxapi_path      /opt/resolve/Developer/Scripting  (found)lib_path      /opt/resolve/libs/fusionscript.so  (found)
--- Import test ---  ok: DaVinciResolveScript imports
--- Live connection ---  ok: connected to Resolve; project = My Project
--- Result ---  All checks passed.

doctor exits 0 when everything works and 1 otherwise, so it is usable in a setup script. When something is wrong it names the exact path that is missing and what to enable.

Register with your MCP client

The server finds Resolve's scripting API by itself, so on a default installation there is nothing to configure:

{  "mcpServers": {    "resolve-ext": { "command": "resolve-ext" }  }}

For a non-standard Resolve location, or to see the explicit form, run:

resolve-ext env

which prints the configuration for the machine it runs on — including the exact RESOLVE_SCRIPT_API, RESOLVE_SCRIPT_LIB and PYTHONPATH values — as generic JSON and as a hermes mcp add command.

When merging into an existing client config, the server entry sits flat under the client's own mcpServers key. Do not wrap it in a second mcpServers level — that silently disables tool discovery.

Resolve settings

Resolve must be running with Preferences → System → General → External scripting using → Local.

Tools

effects

list_available(media_type?)          video (default) | photo | audiolist_applied(item_id?|name?, category?)apply(item_id?|name?, category, id)remove(item_id?|name?, category, indices?)set_enabled(item_id?|name?, index, enabled, category?)reorder(item_id?|name?, index, new_index, category?)

Address a timeline item with item_id (GetUniqueId) or with name plus the track it sits on (track_type default video, track_index default 1).

Always call list_available first — apply needs the category and id it returns. On a stock 21.1.2 Studio that is 36 fusion + 98 ofx effects for video, plus the Fairlight set for audio. Fusion ids look like Fusion/Effects/<category>/<name>.

clip_attrs

options()                                    the full option vocabularycopy(source_id?|source_name?, target_ids?|target_names?, options, ...)read(item_id?|name?)

The API behind the Edit page's Paste Attributes — the lever that makes a per-camera look repeatable: grade one clip, push the same attributes onto every other clip from that camera.

36 options in 6 groups (clip, video, zoom_crop_flip, retime, grade_fusion, audio). Shorthands: copy_all_video, copy_all_audio.

{"colorCorrection": true, "allZoomAttributes": true, "allCropAttributes": true, "videoPlugins": true}

export_frame

item(item_id?|name?, frame_offset, output_type?, file_path?, format?, max_dimension?)media(clip_id, frame_offset, output_type?, file_path?, format?, max_dimension?)timeline(frame_offset, ...)     # broken on 21.1.2 — see below

item and media are verified working. The offset is 0-based and must be below the item's duration. output_type: file (needs file_path) or encodedString (default); for the latter the base64 is decoded and written to out/ next to the server, with only a short prefix returned inline.

folder_ops

parent_of_clip(clip_id)              which bin holds this clipparent_of_folder(path?|folder_id?)   a folder's parent (root has none)path(clip_id?|folder_id?)            "Master/Sub/Bin"find_clip(clip_id)                   locate a clip anywhere in the tree

photo_albums

list() / current() / set_current(album_id?|name?)create(name) / create_from_photos(name, clip_ids) / delete(album_ids?) / rename(...)quick_export_presets() / render_settings(settings?)photos(album_id?|name?) / add_photos(clip_ids) / remove_photos(photo_ids) / current_item()stills(album_id?|name?, all_photos?)photo(photo_id) / rate(photo_id, stars) / flag(photo_id, color?|clear?)clip_color(photo_id, color?|clear?) / versions(photo_id)add_version / load_version / delete_versioncopy_grade / effects_list / effect_apply / effect_remove / fusion_comps / fusion_add

Verified working on 21.1.2.10: 9/9 PhotoAlbum methods, 20/20 PhotoAlbumItem methods, CreatePhotoAlbumFromPhotos, persistent ratings / flags / versions, AddFusionComp on a photo.

add_photos is broken upstream (AddToPhotoAlbum adds nothing) — the action verifies by reading the album back and tells you so. Use create_from_photos, which is the verified path.

Note the split: the album listing methods live on Project, the creating/adding ones on MediaPool, and Resolve answers none of them. The tool resolves the right object per call, because a Resolve proxy makes hasattr report every method on every object.

node_graph

info(item_id?|name?|photo_id?)        node list with labels and colourslabel(node_index, label)              "" clears the labelcolor(node_index, color)              "" clears the colourenable(node_index, enabled)tools(node_index)                     which Fusion/OFX tools sit in the nodelut(node_index, lut_path?)            read, or setcache(node_index, mode?)              read, or setreset_colors()                        photo graphs onlyreset_grades(confirm=true)            destructive — clears the whole grade

Valid node colours: Orange, Apricot, Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, Pink, Tan, Beige, Brown, Chocolate.

Target a timeline clip by item_id/name, or a photo by photo_id. Labels and colours verified persistent across calls.

project_extras

capabilities()                             what this build answers at allrender_presets()                           GetRenderPresetListupdate_render_preset(preset_name)          GUI-dependent, see the broken tablequick_export_enable(preset_name, enabled)  GUI-dependentaudio_formats()                            {display name -> extension}audio_codecs(format_extension)             {description -> codec name}transcription(clip_id, use_nested?)        a clip's transcriptset_transcription(clip_id, transcription)  verified by reading back

audio_formats / audio_codecs VERIFIED: 7 real formats (FLAC, MP3, MP4, MXF OP-Atom, MXF OP1A (IMF), QuickTime, Wave) and their codecs. render_presets VERIFIED: 37 real presets.

camera_comparison

detect()                 which camera each clip is (from its name)grid_2x2()               four cameras in quadrants, scale 0.5split_h() / split_v()    two-up, side by side or stackedlayout(assignments)      explicit {clip_id: {x, y, scale}} — fractions of rasterfullframe(clip_ids)      back to 1.0 zoom, centredmarkers()                timeline markers naming each camerasort_to_bins()           file clips into per-camera bins by namebuild_timeline()         one video track per camera, scenes syncedread()                   current transform of every clip

Camera detection, longest prefix first:

Why this tool exists: the loose scripts this replaces positioned clips with SetProperty("PositionX", …) / "PositionY". MEASURED on 21.1.2.10 those keys return False and are silently ignored — GetProperty gives back False too. Zoom worked, the positioning never did. The real keys are Pan (x, +right) and Tilt (y, +up), in pixels. Every write here is read back, and a transform that does not stick is reported as a failure.

Verified: on a 3840x2160 timeline grid_2x2 puts AcePro at Pan -960, Tilt 540 (top-left) and Go Ultra at Pan 960, Tilt 540 (top-right), read back.

clip_position

get(item_id?|name?)      position + left/right handle offsets   (safe, read-only)enabled()                timeline enabled state

set / move / set_offset / delete_gaps exist in the code but are disabled and transparent about why — they wrap Resolve calls that are broken or destructive on 21.1.2. See the next section.

Measured behaviour on Resolve 21.1.2.10

Everything below was measured against a live Studio build, not read from docs. tests/ reproduces all of it — 132 assertions across four suites, 0 failures.

Working

Broken or destructive — do not use

Gotchas

• TimelineItem.GetProperty("Position") returns a bool on 21.1.2, not coordinates. The position lives in Pan / Tilt (x/y in pixels). RotationAngle is degrees, Opacity 0–100, crop values 0–1, ZoomX/Y a multiplier. All are writable — verify with a read-back.
• Setting a timeline's SetIsEnabled(False) makes GetCurrentTimeline() return None, so every later call reports "No current timeline" until it is switched back on in the GUI.
• MediaPoolItem.GetParentFolder is only useful with a recursive walk of the media pool: ImportMedia drops clips into the currently selected bin, so a root-only lookup reports "not found" while the clip exists one level down.

Testing

Two layers, because DaVinci Resolve cannot run in CI.

Offline — no Resolve needed, this is what CI runs

python tests/test_offline.py

Checks that server.py imports without Resolve present (so pip install followed by resolve-ext --help cannot fail), that all ten tools register, that the CLI returns the right exit codes, and that the platform path resolution produces the correct paths for the OS it finds itself on. Runs on Windows, macOS and Linux — see .github/workflows/test.yml.

Live — needs a running Resolve Studio

python tests/test_e2e.py        # core toolspython tests/test_phase1.py     # photo albums + node graphpython tests/test_extras.py     # render presets, audio formats, transcriptionpython tests/test_camera.py     # camera layouts, labels, markers, sorting
# point at your own media if ~/Pictures has fewer than 3 PNGsRESOLVE_EXT_TEST_MEDIA="D:/stills/*.png" python tests/test_camera.py

162 assertions, 0 failures against Resolve Studio 21.1.2.10 (30 offline + 132 live).

Each suite creates its own scratch project, exercises the tools and deletes it again — they never touch your other projects. Two habits are deliberate:

• Assertions check that values changed and read back, not merely that no error was returned. A write test that passes because nothing moved proves nothing; that is exactly how DeleteGaps and AddToPhotoAlbum were caught reporting success while doing nothing.
• Known-broken calls are asserted to fail honestly. If a future Resolve build fixes AddToPhotoAlbum, its test will start failing — which is the signal to re-measure and update this README, not a broken test.

Design notes

• Extension, not fork. Nothing here duplicates a mainstream server's surface, so both can run side by side without the model having to choose.
• Broken APIs are reported, not hidden. Where Resolve's own call lies (DeleteGaps returning True), the tool says so with the measurement attached, rather than emitting a success the caller cannot trust.
• Destructive APIs are not exposed. SetLeftOffset cannot be undone through the API, so it stays out of the surface and get remains read-only.

Requirements

• DaVinci Resolve Studio 21.1.2+ (earlier builds lack these symbols)
• Windows / macOS / Linux wherever the Resolve scripting API is available
• Python 3.10+ and mcp[cli]>=1.30,<2

License

MIT — see LICENSE.