davinci-mcp

Overview Schema Source Related Servers Discussions Admin

Media (write)

media_write

Destructive

Change media state in DaVinci Resolve's Media Pool—import, organize, relink, mark, rename, flag, and set clip metadata—then read back each change to verify it took effect.

Instructions

Change media state; may overwrite current values. Every change is read back from Resolve (receipt.verified=false means it did not take). op.action (params; * = required):

add_clip_marker(clip*, frame*, color, name, note, duration, custom_data): Add a marker to a Media Pool clip at a frame offset.
add_clip_mattes(clip*, paths*, stereo_eye): Add matte files to a clip.
add_flag(clip*, color*): Add a flag of the given color to a clip.
add_timeline_mattes(paths*): Add matte files as timeline mattes in the current folder.
auto_sync_audio(clips*, settings): Auto-sync audio of clips (needs at least one video and one audio clip).
clear_flags(clip*, color): Clear one flag color, or all flags, of a clip.
clear_mark_in_out(clip*, mark_type): Clear the mark in/out of a clip.
clone_media(source_dir*, target_dirs*, preserve_folder_name, checksum_type): Clone media with checksum verification (21.1+, long-running job). [job]
create_folder(name*, parent, set_current): Create a subfolder in the Media Pool.
create_multicam_clip(clips*, options): Create multicam clip(s) from clips (21.1+); options use live constants.
create_stereo_clip(left*, right*): Create a stereoscopic 3D clip from a left and a right clip.
export_folder_drb(folder*, path*): Export a Media Pool folder as a DRB file.
export_metadata(path*, clips): Export clip metadata to a CSV file.
import_folder_drb(path*, source_clips_path): Import a DRB folder export into the Media Pool.
import_media(items*, folder, via_media_storage): Import files/folders/sequences into the current or a chosen Media Pool folder.
link_full_resolution_media(clip*, path*): Link full-resolution media to a proxy-only clip.
link_proxy_media(clip*, path*): Link a proxy media file to a clip.
monitor_growing_file(clip*): Monitor a clip's file while it keeps growing.
move_clips(clips*, target*): Move clips to another Media Pool folder.
move_folders(folders*, target*): Move folders into another Media Pool folder.
refresh_folders(): Refresh Media Pool folders (collaboration mode).
relink_clips(clips*, folder_path*): Relink clips to media found in a folder.
replace_clip(clip*, path*, preserve_sub_clip): Replace the underlying media of a clip with another file.
reveal_in_storage(path*): Reveal a path in Resolve's Media Storage panel.
select_clip(clip*): Select a clip in the Media Pool.
set_clip_color(clip*, color): Set a clip color (16 clip colors) or clear it when color is null.
set_clip_metadata(clip*, metadata*, third_party): Set clip metadata (or third-party metadata) key/value pairs.
set_clip_name(clip*, name*): Rename a clip (MediaPoolItem.SetName).
set_clip_properties(clip*, properties*): Set clip properties (key -> value), reading each one back.
set_current_folder(folder*): Make a folder the current Media Pool folder.
set_mark_in_out(clip*, mark_in*, mark_out*, mark_type): Set the mark in/out of a clip.
update_marker_custom_data(clip*, frame*, custom_data*): Update the custom data of a clip marker. Shortcuts (prefer them for whole tasks):
workflow_write.conform_from_edl: Import media + EDL as a timeline, fix offline events via Start TC, report linkage. One call instead of import_media, relink_clips. Calls known in advance (a sequence, the same change on several items): ONE batch_run.

Input Schema

Name	Required	Description
`op`	Yes	{action, ...params}. Parameters per action: see the description or this server's describe_action tool.
`dry_run`	No	true: return the planned effect, change nothing.
`snapshot`	No	true: back up the timeline/project first; omitted: server policy.

Output Schema

Name	Required	Description	Default
`job`	No
`plan`	No
`status`	Yes
`receipt`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.4Nov 1, 2026
- addedInput schema / properties / dry_run / description
```
Added value: +"true: return the planned effect, change nothing."
```
- addedInput schema / properties / snapshot / description
```
Added value: +"true: back up the timeline/project first; omitted: server policy."
```
First observedv0.1.0Nov 1, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations: warns 'may overwrite current values,' documents the read-back verification contract (receipt.verified=false means the change did not take), tags clone_media as a long-running [job], notes version gates (21.1+), collaboration-mode requirements, and preconditions such as auto_sync_audio needing one video and one audio clip.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the destructive/verification warning in two sentences, then a single-line-per-action catalog, then shortcuts — a sensible ordering. The 32-line enumeration is long but each line is a distinct discriminator branch, so density is justified rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 32-branch destructive dispatcher this is complete: mutation semantics, verification receipt, job-tagged actions, version constraints, dry_run/snapshot safety knobs are in the schema, and an output schema exists so return shape needn't be restated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema's op object is additionalProperties:true, so the enum alone cannot convey per-action arguments; the description supplies exactly that, marking required params with '*' for every action. This adds meaning the schema cannot express, despite 100% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Change media state') and then enumerates all 32 actions with per-action parameter shapes, so an agent can identify the exact operation it needs. It is clearly the write counterpart to media_read/media_delete and covers every member of the action enum.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes whole-task work to workflow_write.conform_from_edl ('one call instead of import_media, relink_clips') and known-in-advance sequences to batch_run, which is genuine when-to-use guidance. It lacks explicit 'when not to use' framing versus media_delete/media_read beyond the obvious read/write split.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.