DaVinci Resolve

让 AI Agent 在 DaVinci Resolve 中剪辑、调色和交付，每项更改都经过检查。

davinci-mcp 是适用于 DaVinci Resolve 的 MCP 服务。它让 Claude 等 AI Agent 能够使用完整的 Resolve 脚本 API：涵盖 17 个领域的 299 项类型化操作。每项更改都会先与 Resolve 本身核实，确认无误后才报告已完成。

它面向希望由助手代劳点击操作的剪辑师和调色师，也面向希望在 Agent 与 Resolve 之间搭建可靠桥梁的开发者。

查看实际效果

一个真实的 Claude Agent 只收到四条普通消息，就剪出了这支 52 秒的动作预告片，素材来自开放电影 Tears of Steel。它导入了素材，在节拍上排列了 33 个镜头，添加了标题卡，调出青橙色调，并完成渲染。整个过程没有任何摆拍；下方视频以 4 倍速播放。

_{▶ 在 YouTube 上观看完整演示（39 秒）}

_{▶ 在 YouTube 上观看 Agent 剪辑的预告片（52 秒）}

经过验证，而非寄望于运气

• 每次写入后都会从 Resolve 读回，并在回执中标明 verified: true 或 false。Agent 无法声称并未发生的更改已完成。
• dry_run 可预览任何写入，而不实际应用。
• 删除需要征得同意：首次调用会返回计划和 confirm_token，只有再次使用该令牌调用同一操作后，才会删除内容。
• 执行破坏性编辑前，会先为时间线创建安全快照。
• 每次调用都会写入 JSONL 审计日志。

可靠

• 在下方的基准测试中，20 项任务全部通过。社区 MCP 服务通过了 20 项中的 13 项，davinci-mcp-professional 通过了 20 项中的 10 项。
• 会修正接近正确的参数，而不是直接拒绝（fade_out → FadeOut，裸片段名称 → 选择器），并报告每项改写。
• 错误信息可指导操作：会建议正确字段（“你是不是想要”）、指出正确的工具，并说明 Resolve 拒绝了哪项渲染设置。

经济

• batch_run 可在服务端通过一次调用串联整个操作序列，例如从时间线到渲染的 18 个步骤。
• 客户端会延迟加载工具，因此首轮上下文约占 32k tokens。
• 回复和架构都很简洁。与社区服务相比：成本降低 31 %，调用次数减少 60 %。

全面且可扩展

• 涵盖 17 个领域：项目、媒体、时间线、项目项、色彩、Fusion、图库、音频、渲染、交换、AI 工具、UI、应用等。
• 一次调用即可完成的工作流：conform_from_edl、deliver、build_vertical_reel、apply_look、title_overlay。
• 你自己的配方：YAML 模板，也可选择使用 Python。

默认安全

• 文件访问仅限于你允许的文件夹。
• 服务自身的状态、配置和你的 Claude 配置文件始终禁止访问。
• 导入文件夹时绝不会跟随符号链接。

基准测试

无头 Claude Agent（Sonnet）在运行中的 Resolve Studio 21.1 上执行了四项后期制作任务，每项运行五次。编写这些任务的 Agent 从未看过该服务的代码：

• dailies：记录并整理一天的素材；
• promo：使用音乐铺底制作宣传片；
• look：使用版本和静帧进行调色；
• spot QC：复制内容、导出交换文件并渲染指定范围。

每项检查都直接读取 Resolve，而不会通过受测服务。每个 Agent 都在相同的隔离测试框架下运行。完整方法和历史记录 →

关于内置服务。 Resolve 21.1 自带 MCP 服务。它的成本更低，因为它只提供一个工具 run_script_unsafe，让 Agent 在 Resolve 内运行任意 Python 脚本。这样运行步骤虽少，但操作前不会验证、读回、审计或创建快照，也不会确认删除操作。在我们的规模测试中（160 个片段、4 条时间线），它曾将标记放在错误的帧上，却报告任务已完成。davinci-mcp 以略高的成本，换来值得信赖的更改。

像剪辑师一样与它交流

Import the clips in ~/Footage/day03, sort interviews and B-roll into bins, and colour the circled takes green.

Build a 9:16 reel from these three shots, add subtitles from the audio, and render it for Instagram.

Conform this EDL against the media in ~/Rushes and deliver a ProRes master and an H.264 proxy.

Apply the show LUT to every shot of the timeline except the end card, and grab a still of the first shot.

Add a red marker at the start of every shot named "broll_" in Edit_03.

Duplicate the approved cut as "QC", export it as FCPXML and OTIO, and render 01:00:02:00 to 01:00:07:24.

工作原理

flowchart LR
    A["AI agent<br/>Claude, Cursor…"] -->|MCP call| V["Validate<br/>+ repair"]
    V --> C["Consent<br/>deletes only"]
    C --> N["Snapshot<br/>destructive only"]
    N --> X["Call Resolve<br/>one thread"]
    X <-->|scripting API| D[("DaVinci<br/>Resolve")]
    X --> R["Read back<br/>→ receipt"]
    R --> L["Audit log"]
    R -->|"verified: true / false"| A

1. 验证。 Agent 调用某个领域工具，例如 timeline_write，并传入 {"op": {"action": ..., ...}}，参数会根据类型化架构进行检查。系统会修正几乎正确的参数，并报告每项修正。
2. 征求同意并创建快照。 删除操作会先停留在计划阶段，直到获得确认；破坏性编辑则会先创建快照。
3. 调用 Resolve。 调用在单个执行器线程上运行，这是唯一会调用 Resolve 的地方。
4. 读取结果。 服务会从 Resolve 读取结果，并返回包含 verified 的回执。较长的渲染会变成作业，Agent 可以等待其完成。

工具

共有 52 个工具。领域工具命名为 <domain>_read、<domain>_write 和 <domain>_delete，并接收 {"op": {"action": ..., ...}}；它们合计提供约 300 个操作。读取不会产生副作用，写入会返回经过验证的回执，删除则会先请求确认。

• resolve_status - 连接状态、Resolve 版本和版本类型、当前项目、时间线和页面。
• describe_action - 一个或多个操作的精简参数架构。
• search_api - 按名称或描述搜索 Resolve 21.1 脚本 API。
• batch_run - 在一次调用中于服务端运行多个工具调用，并为整个批次请求一次确认。
• workflow_write - 单次调用作业：conform_from_edl、deliver、build_vertical_reel、apply_look、title_overlay。
• recipe_list / recipe_run - 列出并运行 YAML 或 Python 配方；每个步骤都会经过验证、核验和审计。
• project_read / project_write / project_delete - 项目、文件夹、数据库、设置和设置预设；创建、加载、保存、归档、导入、导出。
• media_read / media_write / media_delete - 媒体池和存储：导入、媒体箱、重新链接、代理、元数据、标记、旗标、多机位、遮罩、音频同步。
• timeline_read / timeline_write / timeline_delete - 时间线、轨道、标记、播放头、复合片段和 Fusion 片段、导入和导出。
• item_read / item_write / item_delete - 时间线项目：属性、速度、淡变、替换片段、旗标、颜色、标记、转场、稳定。
• color_read / color_write / color_delete - 节点图、CDL、LUT、版本、调色组、DRX 调色、DCTL。
• fusion_read / fusion_write / fusion_delete - Fusion 合成和工具：添加、连接、输入、关键帧、表达式、Text+ 标题、设置、熔接器。
• gallery_read / gallery_write / gallery_delete - 静帧相册：抓取、导入、导出、添加标签。
• audio_read / audio_write - 响度分析、静音检测、标准化、语音隔离、Fairlight 预设、音频映射。
• render_read / render_write / render_delete - 格式、编解码器、预设和渲染作业；渲染时间线或范围、快速导出。
• interchange_read / interchange_write - EDL、FCPXML、OTIO、标记 CSV 和 .cube LUT 文件，无需通过 Resolve 即可读取和写入。
• ai_read / ai_write / ai_delete - 转录、从音频生成字幕、场景切点检测、Smart Reframe、音频分类、IntelliSearch。
• vision_read - 导出或截取帧和联系表，让 Agent 查看画面。
• ui_read / ui_write / ui_delete - 页面、菜单和键盘快捷键，用于处理少数 API 无法实现的操作。
• app_read / app_write / app_delete - Resolve 应用信息、布局预设、关键帧模式、退出。
• snapshot_list / snapshot_write - 时间线或项目的安全副本，在破坏性编辑前自动创建。
• job_status / job_wait / job_list / job_cancel - 长时间操作（渲染、分析）以作业形式运行。
• code_delete - 在 Resolve 中运行 run_lua 和 run_python，作为默认关闭且始终需要确认的应急通道。

安装

uv tool install davinci-mcp

pipx install davinci-mcp 和 pip install davinci-mcp 也可以使用。

davinci-mcp doctor

doctor 会检查能否连接到 Resolve，并报告其版本、版本类型和通道。

davinci-mcp install --target claude-code

claude mcp add davinci-mcp -- davinci-mcp serve

davinci-mcp install --target claude-desktop

{
  "mcpServers": {
    "davinci-mcp": { "command": "davinci-mcp", "args": ["serve"] }
  }
}

{
  "mcpServers": {
    "davinci-mcp": { "command": "davinci-mcp", "args": ["serve"] }
  }
}

{
  "servers": {
    "davinci-mcp": { "type": "stdio", "command": "davinci-mcp", "args": ["serve"] }
  }
}

可选文件 ~/.config/davinci-mcp/config.toml 用于保存设置。任何键都可以通过 DAVINCI_MCP_<SECTION>__<KEY> 环境变量覆盖。

[safety]
allowed_roots = ["~/Movies", "~/Projects"]  # files outside these are refused (default: your home)
auto_snapshot = "destructive"               # "off" | "destructive" | "all"

[recipes]
allow_python = false                        # Python recipes run arbitrary code: opt in

该文件不会自动创建；未创建时会应用以下默认值。未知键或位于错误分区中的键会导致服务器因验证错误而停止。在环境变量中，列表写作 [~/Movies,~/Footage]。

常见问题

欢迎提交问题和拉取请求。docs/domain-guide.md 介绍了如何添加一个操作：参数模型、处理程序、回读检查和测试。其余内容会据此生成。

uv sync
uv run pytest
uv run ruff check . && uv run pyright

致谢

• 演示视频：Tears of Steel，© Blender Foundation | mango.blender.org，CC-BY 3.0。
• 演示音乐：Kevin MacLeod 创作的 Five Armies（incompetech.com），CC-BY 4.0。

davinci-mcp 是一个独立项目，与 Blackmagic Design 无关，也未获其认可或赞助。DaVinci Resolve 是 Blackmagic Design Pty. Ltd. 的商标。

支持

davinci-mcp 免费且开源。如果它为你节省了剪辑时间，可以请我喝杯咖啡：

由 Delanoe Pirard（Aedelon）制作 · Apache 2.0