达芬奇 Resolve MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供对达芬奇 Resolve 脚本 API 的 完全覆盖。将 AI 助手（Claude、Cursor、Windsurf）连接到达芬奇 Resolve，并通过自然语言控制您的后期制作工作流程的各个方面。

v2.1.0 新特性

• 新增 fusion_comp 工具 — 该工具包含 20 个操作，公开了完整的 Fusion 合成节点图 API。您可以在当前活动的 Fusion 页面合成上添加/删除/查找节点、连接线、设置/获取参数、管理关键帧、控制撤销分组、设置渲染范围以及触发渲染。
• timeline_item_fusion 缓存操作 — 添加了 get_cache_enabled 和 set_cache 操作，用于直接在时间线项目上控制 Fusion 输出缓存。
• Fusion 节点图参考 — 文档字符串中包含了常见工具 ID（Merge、TextPlus、Background、Transform、ColorCorrector、DeltaKeyer 等），便于发现和使用。

v2.0.9

• 跨平台沙盒路径重定向 — _resolve_safe_dir() 现在可以处理 macOS（/var/folders、/private/var）、Linux（/tmp、/var/tmp）和 Windows（AppData\Local\Temp）等 Resolve 无法写入的沙盒路径。这些路径将被重定向到 ~/Documents/resolve-stills，而不是桌面。
• grab_and_export 自动清理 — 导出的文件会被读取到响应中（DRX 作为内联文本，图片为 base64 格式），然后自动从磁盘上删除。不会产生任何文件堆积。如果希望保留文件在磁盘上，可以传递 cleanup: false 参数。
• 两台服务器同步 — server.py 和 resolve_mcp_server.py 现在共享相同版本，并且都使用 _resolve_safe_dir() 来处理所有面向 Resolve 的临时路径（项目导出、LUT 导出、静止图像导出）。

v2.0.8

• gallery_stills 上新增 grab_and_export 操作 — 将 GrabStill() 和 ExportStills() 合并为一个原子调用，同时保留 Live GalleryStill 引用以确保可靠导出。返回包含已导出图像及配套 .drx 调色文件的文件清单。
• 格式回退链 — 如果请求的格式失败，将自动尝试 tif 格式，然后再是 dpx 格式。
• macOS 沙盒路径重定向 — /var/folders 和 /private/var 路径将被重定向到 ~/Desktop/resolve-stills 目录，因为 Resolve 进程无法写入沙盒化的临时目录。
• 关键发现记录在案 — ExportStills 需要 Color 页面上的 Gallery 面板处于可见状态。所有 9 种支持的格式（dpx、cin、tif、jpg、png、ppm、bmp、xpm、drx）都会在导出图像的同时生成配套的 .drx 调色文件。

v2.0.7

• 安全性：布局预设工具的路径遍历防护 — export_layout_preset、import_layout_preset 和 delete_layout_preset 现在会验证解析后的文件路径是否位于预期的 Resolve 预设目录内，从而防止通过精心构造的预设名称进行路径遍历。
• 安全性：破坏性工具风险说明 — 增加了“安全注意事项”章节，指出 quit_app 和 restart_app 工具可能会终止 Resolve 程序；因此，MCP 客户端在调用这些工具前应要求用户确认。

v2.0.6

• 修复颜色组操作崩溃问题 — timeline_item_color 中的 _check() 被解包为 (proj, _, _)，但实际返回值为 (pm, proj, err)，导致 proj 接收到的是 ProjectManager 对象而非 Project 对象，从而引发 assign_color_group 和 remove_from_color_group 函数崩溃。

v2.0.5

• 懒加载连接恢复 — 全功能服务器（--full 模式）现在会自动重新连接并启动 Resolve，与复合服务器的行为一致。
• 所有链式 API 调用的空值保护 — 如果 GetProjectManager()、GetCurrentProject() 或 GetCurrentTimeline() 执行失败，现在会返回明确的错误信息，而不是抛出 NoneType 错误。
• 辅助函数 — get_resolve()、get_project_manager() 和 get_current_project() 替代了 178 处重复代码块。

v2.0.4

• 修复 apply_grade_from_drx 参数问题 — 将 mode 重命名为 grade_mode，以匹配 Resolve API；同时修正了文档中的描述，将其从“替换/追加”更正为实际的关键帧对齐模式（0=无关键帧，1=源时间码对齐，2=起始帧对齐）。
• 向后兼容 — 现在仍然接受 mode 参数以供现有客户端使用，但优先采用 grade_mode 参数。

v2.0.3

• 修复 GetNodeGraph 崩溃问题 — 在 Resolve 中，GetNodeGraph(0) 会返回 False；现在除非显式提供 layer_index 参数，否则将不进行调用。
• 假值节点图检查 — 使用 not g 而不是 g is None 来检查节点图，以捕获 False 返回值。

v2.0.2

• 反重力支持 — Google 的代理型 AI 编程助手被添加为第 10 个 MCP 客户端。
• 按字母顺序排列客户端 — MCP_CLIENTS 列表已排序，便于维护。

v2.0.1

• 26 工具复合服务器 — 所有 324 个 API 方法被分组为 26 个上下文高效的工具（默认）。
• 通用安装程序 — 单一的 python install.py 可用于 macOS/Windows/Linux，支持 10 个 MCP 客户端。
• 专用的时间线项目操作 — 包括速度调整、变换、裁剪、合成、音频以及带验证的关键帧操作。
• 懒加载 Resolve 连接 — 服务器会立即启动，直到首次调用工具时才连接 Resolve。
• Bug 修复 — 包括 CreateMagicMask 参数类型、GetCurrentClipThumbnailImage 参数以及 Python 3.13+ 警告。

关键统计数据

指标	数值
MCP 工具	26 个复合工具（默认） / 342 个细粒度工具
覆盖的 API 方法	324/324（100%）
实际测试的 API 方法	319/324（98.5%）
实测通过率	319/319（100%）
API 对象类	13
测试版本	DaVinci Resolve 19.1.3 Studio

API 覆盖范围

DaVinci Resolve 脚本 API 中所有未弃用的方法均已覆盖。默认的复合服务器公开了 27 个工具，这些工具按操作参数将相关功能分组，从而保持 LLM 上下文窗口的简洁。而完整细粒度服务器则为高级用户提供 342 个独立工具。两种模式均覆盖了全部 13 个 API 对象类：

类别	方法数	工具数	描述
Resolve	21	21	应用程序控制、页面、布局预设、渲染/烧录预设、关键帧模式
ProjectManager	25	25	项目增删改查、文件夹、数据库、云项目、归档与恢复
Project	42	42	时间线、渲染流程、设置、LUT、颜色组
MediaStorage	9	9	卷、文件浏览、媒体导入、遮罩
MediaPool	27	27	文件夹、片段、时间线、元数据、立体声、同步
Folder	8	8	片段列表、导出、转录
MediaPoolItem	32	32	元数据、标记、标志、属性、代理、转录
Timeline	56	56	轨道、标记、片段、导出、生成器、字幕、静止图像、立体声
TimelineItem	76	76	属性、标记、Fusion 合成、版本、take、CDL、AI 工具
Gallery	8	8	相册、静止图像、高级调色
GalleryStillAlbum	6	6	静止图像管理、导入导出、标签
Graph	11	22	节点操作、LUT、缓存、调色（时间线和片段图变体）
ColorGroup	5	10	组管理、片段前/后节点图

系统要求

• DaVinci Resolve Studio 18.5+（macOS、Windows 或 Linux）——免费版不支持外部脚本
• 推荐使用 Python 3.10–3.12（3.13+ 可能与 Resolve 的脚本库存在 ABI 不兼容问题）
• DaVinci Resolve 需在 偏好设置 > 常规 > “外部脚本” 设置为 本地 的情况下运行

快速入门

# 克隆仓库
git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
cd davinci-resolve-mcp

# 确保 DaVinci Resolve 已启动，然后：
python install.py

通用安装程序会自动检测您的平台、查找 DaVinci Resolve 安装路径、创建虚拟环境并配置您的 MCP 客户端——所有步骤一步完成。

支持的 MCP 客户端

安装程序可自动配置以下任一客户端：

客户端	配置写入位置
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Claude Code	.mcp.json（项目根目录）
Cursor	~/.cursor/mcp.json
VS Code (Copilot)	.vscode/mcp.json（工作区）
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	VS Code 全局存储
Roo Code	VS Code 全局存储
Zed	~/.config/zed/settings.json
Continue	~/.continue/config.json
JetBrains IDEs	手动配置（设置 > 工具 > AI 助手 > MCP）

您可以同时配置多个客户端，或使用 --clients manual 来获取可复制粘贴的配置片段。

安装选项

python install.py                              # 交互模式
python install.py --clients all                # 配置所有客户端
python install.py --clients cursor,claude-desktop  # 指定客户端
python install.py --clients manual             # 仅输出配置
python install.py --dry-run --clients all      # 预览而不写入
python install.py --no-venv --clients cursor   # 跳过虚拟环境创建

服务器模式

MCP 服务器有两种模式：

模式	文件	工具数	适用人群
复合（默认）	src/server.py	26	大多数用户——快速、简洁、低上下文占用
完整	src/resolve_mcp_server.py	342	希望每个 API 方法对应一个工具的高级用户

复合服务器的 timeline_item 工具包含针对常见工作流的专用操作：

类别	操作	参数
变速	get_retime, set_retime	处理方式（最近、帧混合、光流）、运动估计（0-6）
变换	get_transform, set_transform	平移、倾斜、缩放X/Y、旋转角度、锚点X/Y、俯仰、偏航、翻转X/Y
裁剪	get_crop, set_crop	左裁剪、右裁剪、上裁剪、下裁剪、裁剪柔化程度、是否保留裁剪区域
合成	get_composite, set_composite	不透明度、合成模式
音频	get_audio, set_audio	音量、声像、音频同步偏移
关键帧	get_keyframes, add_keyframe, modify_keyframe, delete_keyframe, set_keyframe_interpolation	属性、帧、值、插值方式（线性、贝塞尔、缓入、缓出、缓入缓出）

安装程序默认使用复合服务器。如需使用完整服务器：

python src/server.py --full    # 启动完整的 342 工具服务器
# 或直接将您的 MCP 配置指向 src/resolve_mcp_server.py

手动配置

如果您更倾向于自行设置，请在您的 MCP 客户端配置中添加以下内容：

{
  "mcpServers": {
    "davinci-resolve": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/davinci-resolve-mcp/src/server.py"]
    }
  }
}

各平台的具体路径如下：

平台	API 路径	库文件路径
macOS	/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting	fusionscript.so 在 DaVinci Resolve.app 中
Windows	C:\ProgramData\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting	fusionscript.dll 在 Resolve 安装目录中
Linux	/opt/resolve/Developer/Scripting	/opt/resolve/libs/Fusion/fusionscript.so

使用示例

连接成功后，您可以通过自然语言控制 DaVinci Resolve：

“当前运行的 DaVinci Resolve 是哪个版本？”
“列出所有项目，并打开名为‘我的电影’的项目”
“创建一个名为‘粗剪’的新时间线，并将媒体池中的所有片段添加进去”
“在当前播放头位置添加一个蓝色标记，备注‘待审核’”
“为当前时间线设置 ProRes 422 HQ 渲染”
“将时间线导出为 EDL”
“切换到调色页面，并截取一张静止图像”
“在选中的片段上创建一个 Fusion 合成”

测试结果

所有测试均基于 macOS 上的 DaVinci Resolve 19.1.3 Studio 进行，采用实时 API 调用（无模拟）。

阶段	测试数	通过率	范围
第一阶段	204/204	100%	所有类别的安全只读操作
第二阶段	79/79	100%	采用创建-测试-清理模式的破坏性操作
第三阶段	20/20	100%	实际媒体导入、同步、转录、数据库切换、Resolve.Quit
第四阶段	10/10	100%	AI/ML 方法、Fusion 片段、立体声、画廊静止图像
第五阶段	6/6	100%	场景剪辑、从音频提取字幕、图表节点缓存/工具/启用
总计	319/319	100%	98.5% 的所有 API 方法均经过实时测试

未测试的方法（5/324）

方法	原因	需要帮助
PM.CreateCloudProject	需要 DaVinci Resolve 云基础设施	是
PM.LoadCloudProject	需要 DaVinci Resolve 云基础设施	是
PM.ImportCloudProject	需要 DaVinci Resolve 云基础设施	是
PM.RestoreCloudProject	需要 DaVinci Resolve 云基础设施	是
TL.AnalyzeDolbyVision	需要 HDR/Dolby Vision 内容	是

---

完整 API 参考

DaVinci Resolve 脚本 API 中的每个方法及其测试状态。方法按对象类列出。

状态说明：

• ✅ = 已现场测试，返回预期结果
• ⚠️ = 已现场测试，API 接受调用（返回 False — 需要特定上下文才能完全执行）
• ☁️ = 需要云基础设施（未测试）
• 🔬 = 需要特定内容/硬件（未测试 — 欢迎提交 PR）

Resolve

#	方法	状态	测试结果 / 备注
1	Fusion()	✅	返回 Fusion 对象
2	GetMediaStorage()	✅	返回 MediaStorage 对象
3	GetProjectManager()	✅	返回 ProjectManager 对象
4	OpenPage(pageName)	✅	切换 Resolve 页面
5	GetCurrentPage()	✅	返回当前页面名称（例如 "edit"）
6	GetProductName()	✅	返回 "DaVinci Resolve Studio"
7	GetVersion()	✅	返回 [19, 1, 3, 7, '']
8	GetVersionString()	✅	返回 "19.1.3.7"
9	LoadLayoutPreset(presetName)	✅	加载已保存的布局
10	UpdateLayoutPreset(presetName)	✅	更新现有预设
11	ExportLayoutPreset(presetName, presetFilePath)	✅	将预设导出到文件
12	DeleteLayoutPreset(presetName)	✅	删除预设
13	SaveLayoutPreset(presetName)	⚠️	API 接受；当预设名称冲突时返回 False
14	ImportLayoutPreset(presetFilePath, presetName)	✅	从文件导入预设
15	Quit()	✅	退出 DaVinci Resolve
16	ImportRenderPreset(presetPath)	⚠️	API 接受；需要有效的预设文件
17	ExportRenderPreset(presetName, exportPath)	⚠️	API 接受；需要有效的预设名称
18	ImportBurnInPreset(presetPath)	⚠️	API 接受；需要有效的预设文件
19	ExportBurnInPreset(presetName, exportPath)	⚠️	API 接受；需要有效的预设名称
20	GetKeyframeMode()	✅	返回关键帧模式
21	SetKeyframeMode(keyframeMode)	⚠️	API 接受；模式必须匹配有效枚举

ProjectManager

#	方法	状态	测试结果 / 备注
1	ArchiveProject(projectName, filePath, ...)	⚠️	API 接受；归档过程较慢
2	CreateProject(projectName)	✅	创建新项目
3	DeleteProject(projectName)	⚠️	如果项目已打开，则返回 False
4	LoadProject(projectName)	✅	返回 Project 对象
5	GetCurrentProject()	✅	返回当前项目
6	SaveProject()	✅	保存当前项目
7	CloseProject(project)	✅	关闭项目
8	CreateFolder(folderName)	✅	创建项目文件夹
9	DeleteFolder(folderName)	✅	删除项目文件夹
10	GetProjectListInCurrentFolder()	✅	返回项目名称列表
11	GetFolderListInCurrentFolder()	✅	返回文件夹名称列表
12	GotoRootFolder()	✅	导航到根目录
13	GotoParentFolder()	✅	在根目录时返回 False（符合预期）
14	GetCurrentFolder()	✅	返回当前文件夹名称
15	OpenFolder(folderName)	✅	打开文件夹
16	ImportProject(filePath, projectName)	✅	导入 .drp 文件
17	ExportProject(projectName, filePath, ...)	✅	导出 .drp 文件
18	RestoreProject(filePath, projectName)	⚠️	API 接受；需要备份存档
19	GetCurrentDatabase()	✅	返回 {DbType, DbName}
20	GetDatabaseList()	✅	返回数据库列表
21	SetCurrentDatabase({dbInfo})	✅	切换数据库
22	CreateCloudProject({cloudSettings})	☁️	需要云基础设施
23	LoadCloudProject({cloudSettings})	☁️	需要云基础设施
24	ImportCloudProject(filePath, {cloudSettings})	☁️	需要云基础设施
25	RestoreCloudProject(folderPath, {cloudSettings})	☁️	需要云基础设施

项目

序号	方法	状态	测试结果/备注
1	GetMediaPool()	✅	返回 MediaPool 对象
2	GetTimelineCount()	✅	返回整数计数
3	GetTimelineByIndex(idx)	✅	返回 Timeline 对象
4	GetCurrentTimeline()	✅	返回当前 Timeline
5	SetCurrentTimeline(timeline)	✅	设置活动 Timeline
6	GetGallery()	✅	返回 Gallery 对象
7	GetName()	✅	返回项目名称
8	SetName(projectName)	⚠️	在打开的项目中返回 False
9	GetPresetList()	✅	返回包含维度的预设列表
10	SetPreset(presetName)	⚠️	API 接受；预设必须存在
11	AddRenderJob()	✅	返回作业 ID 字符串
12	DeleteRenderJob(jobId)	✅	删除渲染作业
13	DeleteAllRenderJobs()	✅	清空渲染队列
14	GetRenderJobList()	✅	返回作业列表
15	GetRenderPresetList()	✅	返回预设名称
16	StartRendering(...)	✅	开始渲染
17	StopRendering()	✅	停止渲染
18	IsRenderingInProgress()	✅	空闲时返回 False
19	LoadRenderPreset(presetName)	✅	加载渲染预设
20	SaveAsNewRenderPreset(presetName)	✅	创建渲染预设
21	DeleteRenderPreset(presetName)	✅	删除渲染预设
22	SetRenderSettings({settings})	✅	应用渲染设置
23	GetRenderJobStatus(jobId)	✅	返回 {JobStatus, CompletionPercentage}
24	GetQuickExportRenderPresets()	✅	返回预设名称
25	RenderWithQuickExport(preset, {params})	✅	启动快速导出
26	GetSetting(settingName)	✅	返回项目设置字典
27	SetSetting(settingName, settingValue)	✅	设置项目设置
28	GetRenderFormats()	✅	返回格式映射
29	GetRenderCodecs(renderFormat)	✅	返回编解码器映射
30	GetCurrentRenderFormatAndCodec()	✅	返回 {format, codec}
31	SetCurrentRenderFormatAndCodec(format, codec)	✅	设置格式和编解码器
32	GetCurrentRenderMode()	✅	返回模式整数
33	SetCurrentRenderMode(renderMode)	✅	设置渲染模式
34	GetRenderResolutions(format, codec)	✅	返回分辨率列表
35	RefreshLUTList()	✅	刷新 LUT 列表
36	GetUniqueId()	✅	返回 UUID 字符串
37	InsertAudioToCurrentTrackAtPlayhead(...)	⚠️	已测试；需要 Fairlight 页面上下文
38	LoadBurnInPreset(presetName)	⚠️	API 接受；预设必须存在
39	ExportCurrentFrameAsStill(filePath)	⚠️	API 接受；需要有效的播放头位置
40	GetColorGroupsList()	✅	返回颜色组列表
41	AddColorGroup(groupName)	✅	返回 ColorGroup 对象
42	DeleteColorGroup(colorGroup)	✅	删除颜色组

媒体存储

序号	方法	状态	测试结果/备注
1	GetMountedVolumeList()	✅	返回已挂载卷路径
2	GetSubFolderList(folderPath)	✅	返回子文件夹路径
3	GetFileList(folderPath)	✅	返回文件路径
4	RevealInStorage(path)	✅	在媒体存储中显示路径
5	AddItemListToMediaPool(...)	✅	导入媒体，返回片段
6	AddClipMattesToMediaPool(item, [paths], eye)	✅	添加片段遮罩
7	AddTimelineMattesToMediaPool([paths])	✅	返回 MediaPoolItem 列表

媒体池

序号	方法	状态	测试结果/备注
1	GetRootFolder()	✅	返回根文件夹
2	AddSubFolder(folder, name)	✅	创建子文件夹
3	RefreshFolders()	✅	刷新文件夹列表
4	CreateEmptyTimeline(name)	✅	创建时间线
5	AppendToTimeline(...)	✅	追加片段，返回 TimelineItems
6	CreateTimelineFromClips(name, ...)	✅	从片段创建时间线
7	ImportTimelineFromFile(filePath, {options})	✅	导入 AAF/EDL/XML
8	DeleteTimelines([timeline])	✅	删除时间线
9	GetCurrentFolder()	✅	返回当前文件夹
10	SetCurrentFolder(folder)	✅	设置当前文件夹
11	DeleteClips([clips])	✅	删除片段
12	ImportFolderFromFile(filePath)	✅	导入 DRB 文件夹
13	DeleteFolders([subfolders])	✅	删除文件夹
14	MoveClips([clips], targetFolder)	✅	移动片段
15	MoveFolders([folders], targetFolder)	✅	移动文件夹
16	GetClipMatteList(item)	✅	返回遮罩路径
17	GetTimelineMatteList(folder)	✅	返回遮罩项目
18	DeleteClipMattes(item, [paths])	✅	删除片段遮罩
19	RelinkClips([items], folderPath)	⚠️	API 接受；需要离线片段
20	UnlinkClips([items])	✅	解除片段链接
21	ImportMedia([items])	✅	导入媒体文件
22	ExportMetadata(fileName, [clips])	✅	导出元数据 CSV
23	GetUniqueId()	✅	返回 UUID 字符串
24	CreateStereoClip(left, right)	✅	创建立体声对
25	AutoSyncAudio([items], {settings})	⚠️	已测试；需要匹配的音视频片段
26	GetSelectedClips()	✅	返回选定的片段
27	SetSelectedClip(item)	✅	选择片段

文件夹

序号	方法	状态	测试结果/备注
1	GetClipList()	✅	返回片段列表
2	GetName()	✅	返回文件夹名称
3	GetSubFolderList()	✅	返回子文件夹列表
4	GetIsFolderStale()	✅	返回 False
5	GetUniqueId()	✅	返回 UUID 字符串
6	Export(filePath)	✅	导出 DRB 文件
7	TranscribeAudio()	✅	开始音频转录
8	ClearTranscription()	✅	清除转录内容

MediaPoolItem

序号	方法	状态	测试结果/备注
1	GetName()	✅	返回片段名称
2	GetMetadata(metadataType)	✅	返回元数据字典
3	SetMetadata(type, value)	✅	设置元数据
4	GetThirdPartyMetadata(type)	✅	返回第三方元数据
5	SetThirdPartyMetadata(type, value)	✅	设置第三方元数据
6	GetMediaId()	✅	返回媒体 UUID
7	AddMarker(frameId, color, name, note, duration, customData)	✅	添加标记
8	GetMarkers()	✅	返回标记字典
9	GetMarkerByCustomData(customData)	✅	根据数据查找标记
10	UpdateMarkerCustomData(frameId, customData)	✅	更新标记数据
11	GetMarkerCustomData(frameId)	✅	返回自定义数据字符串
12	DeleteMarkersByColor(color)	✅	按颜色删除标记
13	DeleteMarkerAtFrame(frameNum)	⚠️	如果该帧无标记，则返回 False
14	DeleteMarkerByCustomData(customData)	⚠️	如果没有匹配项，则返回 False
15	AddFlag(color)	✅	添加标志
16	GetFlagList()	✅	返回标志颜色
17	ClearFlags(color)	✅	清除标志
18	GetClipColor()	✅	返回片段颜色
19	SetClipColor(colorName)	✅	设置片段颜色
20	ClearClipColor()	✅	清除片段颜色
21	GetClipProperty(propertyName)	✅	返回属性字典
22	SetClipProperty(propertyName, value)	⚠️	API 接受；但部分属性只读
23	LinkProxyMedia(proxyMediaFilePath)	✅	链接代理媒体
24	UnlinkProxyMedia()	✅	取消链接代理媒体
25	ReplaceClip(filePath)	✅	替换片段源文件
26	GetUniqueId()	✅	返回 UUID 字符串
27	TranscribeAudio()	✅	开始音频转录
28	ClearTranscription()	✅	清除转录内容
29	GetAudioMapping()	✅	返回 JSON 格式的音频映射
30	GetMarkInOut()	✅	返回入点/出点字典
31	SetMarkInOut(in, out, type)	✅	设置入点/出点
32	ClearMarkInOut(type)	✅	清除入点/出点

时间线

序号	方法	状态	测试结果/备注
1	GetName()	✅	返回时间线索引名称
2	SetName(timelineName)	⚠️	在活动时间线上返回 False
3	GetStartFrame()	✅	返回起始帧
4	GetEndFrame()	✅	返回结束帧
5	SetStartTimecode(timecode)	✅	设置开始时间码
6	GetStartTimecode()	✅	返回 "01:00:00:00"
7	GetTrackCount(trackType)	✅	返回轨道数量
8	AddTrack(trackType, subTrackType)	✅	添加轨道
9	DeleteTrack(trackType, trackIndex)	✅	删除轨道
10	GetTrackSubType(trackType, trackIndex)	✅	返回子类型（例如 "stereo"）
11	SetTrackEnable(trackType, trackIndex, enabled)	✅	启用或禁用轨道
12	GetIsTrackEnabled(trackType, trackIndex)	✅	返回启用状态
13	SetTrackLock(trackType, trackIndex, locked)	✅	锁定或解锁轨道
14	GetIsTrackLocked(trackType, trackIndex)	✅	返回锁定状态
15	DeleteClips([timelineItems], ripple)	✅	从时间线删除片段
16	SetClipsLinked([timelineItems], linked)	✅	链接或取消链接片段
17	GetItemListInTrack(trackType, index)	✅	返回轨道上的项目列表
18	AddMarker(frameId, color, name, note, duration, customData)	✅	添加时间线标记
19	GetMarkers()	✅	返回标记字典
20	GetMarkerByCustomData(customData)	✅	根据数据查找标记
21	UpdateMarkerCustomData(frameId, customData)	✅	更新标记数据
22	GetMarkerCustomData(frameId)	✅	返回自定义数据
23	DeleteMarkersByColor(color)	✅	按颜色删除标记
24	DeleteMarkerAtFrame(frameNum)	⚠️	如果该帧无标记，则返回 False
25	DeleteMarkerByCustomData(customData)	⚠️	如果没有匹配项，则返回 False
26	GetCurrentTimecode()	✅	返回时间码字符串
27	SetCurrentTimecode(timecode)	⚠️	如果播放未激活，则返回 False
28	GetCurrentVideoItem()	✅	返回播放头处的项目
29	GetCurrentClipThumbnailImage()	✅	返回缩略图数据
30	GetTrackName(trackType, trackIndex)	✅	返回轨道名称
31	SetTrackName(trackType, trackIndex, name)	✅	设置轨道名称
32	DuplicateTimeline(timelineName)	✅	复制时间线
33	CreateCompoundClip([items], {clipInfo})	✅	返回复合片段项目
34	CreateFusionClip([timelineItems])	✅	返回 Fusion 片段项目
35	ImportIntoTimeline(filePath, {options})	⚠️	已测试；结果取决于文件格式
36	Export(fileName, exportType, exportSubtype)	✅	导出 EDL/XML/AAF 文件
37	GetSetting(settingName)	✅	返回设置字典
38	SetSetting(settingName, settingValue)	⚠️	API 接受；但部分设置只读
39	InsertGeneratorIntoTimeline(name)	✅	插入生成器
40	InsertFusionGeneratorIntoTimeline(name)	✅	插入 Fusion 生成器
41	InsertFusionCompositionIntoTimeline()	✅	插入 Fusion 合成
42	InsertOFXGeneratorIntoTimeline(name)	⚠️	API 接受；需要有效的 OFX 插件
43	InsertTitleIntoTimeline(name)	✅	插入标题
44	InsertFusionTitleIntoTimeline(name)	✅	插入 Fusion 标题
45	GrabStill()	✅	返回 GalleryStill 对象
46	GrabAllStills(stillFrameSource)	✅	返回 GalleryStill 对象列表
47	GetUniqueId()	✅	返回 UUID 字符串
48	CreateSubtitlesFromAudio({settings})	✅	返回 True — 从音频创建字幕
49	DetectSceneCuts()	✅	返回 True — 检测时间线中的场景切换
50	ConvertTimelineToStereo()	✅	将时间线转换为立体 3D
51	GetNodeGraph()	✅	返回 Graph 对象
52	AnalyzeDolbyVision([items], analysisType)	🔬	需要 HDR/Dolby Vision 内容
53	GetMediaPoolItem()	✅	返回时间线对应的 MediaPoolItem
54	GetMarkInOut()	✅	返回入点/出点字典
55	SetMarkInOut(in, out, type)	✅	设置入点/出点
56	ClearMarkInOut(type)	✅	清除入点/出点

TimelineItem

序号	方法	状态	测试结果/备注
1	GetName()	✅	返回项目名称
2	GetDuration(subframe_precision)	✅	返回持续时间
3	GetEnd(subframe_precision)	✅	返回结束帧
4	GetSourceEndFrame()	✅	返回源素材的结束帧
5	GetSourceEndTime()	✅	返回源素材的结束时间
6	GetFusionCompCount()	✅	返回合成数量
7	GetFusionCompByIndex(compIndex)	✅	返回 Fusion 合成
8	GetFusionCompNameList()	✅	返回合成名称列表
9	GetFusionCompByName(compName)	✅	返回 Fusion 合成
10	GetLeftOffset(subframe_precision)	✅	返回左侧偏移量
11	GetRightOffset(subframe_precision)	✅	返回右侧偏移量
12	GetStart(subframe_precision)	✅	返回起始帧
13	GetSourceStartFrame()	✅	返回源素材的起始帧
14	GetSourceStartTime()	✅	返回源素材的开始时间
15	SetProperty(propertyKey, propertyValue)	✅	设置项目属性
16	GetProperty(propertyKey)	✅	返回属性字典
17	AddMarker(frameId, color, name, note, duration, customData)	✅	向项目添加标记
18	GetMarkers()	✅	返回标记字典
19	GetMarkerByCustomData(customData)	✅	根据自定义数据查找标记
20	UpdateMarkerCustomData(frameId, customData)	✅	更新标记的自定义数据
21	GetMarkerCustomData(frameId)	✅	返回自定义数据
22	DeleteMarkersByColor(color)	✅	按颜色删除标记
23	DeleteMarkerAtFrame(frameNum)	⚠️	如果该帧没有标记，则返回 False
24	DeleteMarkerByCustomData(customData)	⚠️	如果没有匹配的标记，则返回 False
25	AddFlag(color)	✅	添加标志
26	GetFlagList()	✅	返回标志颜色列表
27	ClearFlags(color)	✅	清除标志
28	GetClipColor()	✅	返回片段颜色
29	SetClipColor(colorName)	✅	设置片段颜色
30	ClearClipColor()	✅	清除片段颜色
31	AddFusionComp()	✅	创建 Fusion 合成
32	ImportFusionComp(path)	✅	导入 .comp 文件
33	ExportFusionComp(path, compIndex)	✅	导出 .comp 文件
34	DeleteFusionCompByName(compName)	⚠️	如果找不到合成，则返回 False
35	LoadFusionCompByName(compName)	✅	加载合成
36	RenameFusionCompByName(oldName, newName)	✅	重命名合成
37	AddVersion(versionName, versionType)	✅	添加分级版本
38	GetCurrentVersion()	✅	返回版本信息
39	DeleteVersionByName(versionName, versionType)	⚠️	如果未找到版本，则返回 False
40	LoadVersionByName(versionName, versionType)	✅	加载分级版本
41	RenameVersionByName(oldName, newName, type)	✅	重命名版本
42	GetVersionNameList(versionType)	✅	返回版本名称列表
43	GetMediaPoolItem()	✅	返回源 MediaPool 项
44	GetStereoConvergenceValues()	✅	返回立体关键帧
45	GetStereoLeftFloatingWindowParams()	✅	返回立体参数
46	GetStereoRightFloatingWindowParams()	✅	返回立体参数
47	SetCDL([CDL map])	✅	设置 CDL 值
48	AddTake(mediaPoolItem, startFrame, endFrame)	✅	添加拍摄片段
49	GetSelectedTakeIndex()	✅	返回选中拍摄片段的索引
50	GetTakesCount()	✅	返回拍摄片段数量
51	GetTakeByIndex(idx)	✅	返回拍摄片段信息
52	DeleteTakeByIndex(idx)	✅	删除拍摄片段
53	SelectTakeByIndex(idx)	✅	选择拍摄片段
54	FinalizeTake()	⚠️	如果没有选中拍摄片段，则返回 False
55	CopyGrades([tgtTimelineItems])	⚠️	API 接受；需要匹配的项目
56	SetClipEnabled(enabled)	✅	启用或禁用片段
57	GetClipEnabled()	✅	返回启用状态
58	UpdateSidecar()	⚠️	对非 BRAW 片段返回 False
59	GetUniqueId()	✅	返回 UUID 字符串
60	LoadBurnInPreset(presetName)	⚠️	API 接受；预设必须存在
61	CreateMagicMask(mode)	⚠️	已测试；需要 DaVinci Neural Engine 和 Color 页面上下文
62	RegenerateMagicMask()	⚠️	已测试；需要现有遮罩
63	Stabilize()	✅	在支持的片段上返回 True
64	SmartReframe()	⚠️	已测试；需要特定的宽高比设置
65	GetNodeGraph(layerIdx)	✅	返回 Graph 对象
66	GetColorGroup()	✅	返回 ColorGroup
67	AssignToColorGroup(colorGroup)	✅	分配到组
68	RemoveFromColorGroup()	⚠️	如果不在组中，则返回 False
69	ExportLUT(exportType, path)	✅	导出 LUT 文件
70	GetLinkedItems()	✅	返回关联项目
71	GetTrackTypeAndIndex()	✅	返回 [trackType, trackIndex]
72	GetSourceAudioChannelMapping()	✅	返回音频映射
73	GetIsColorOutputCacheEnabled()	✅	返回缓存状态
74	GetIsFusionOutputCacheEnabled()	✅	返回缓存状态
75	SetColorOutputCache(cache_value)	⚠️	已测试；需要激活的颜色流程
76	SetFusionOutputCache(cache_value)	⚠️	已测试；需要激活的 Fusion 流程

Gallery

序号	方法	状态	测试结果/备注
1	GetAlbumName(galleryStillAlbum)	✅	返回相册名称
2	SetAlbumName(galleryStillAlbum, albumName)	✅	设置相册名称
3	GetCurrentStillAlbum()	✅	返回 GalleryStillAlbum
4	SetCurrentStillAlbum(galleryStillAlbum)	✅	设置当前相册
5	GetGalleryStillAlbums()	✅	返回相册列表
6	GetGalleryPowerGradeAlbums()	✅	返回功率分级相册
7	CreateGalleryStillAlbum()	✅	创建静止相册
8	CreateGalleryPowerGradeAlbum()	✅	创建功率分级相册

GalleryStillAlbum

序号	方法	状态	测试结果/备注
1	GetStills()	✅	返回 GalleryStill 对象列表
2	GetLabel(galleryStill)	✅	返回标签字符串
3	SetLabel(galleryStill, label)	⚠️	API 接受；但在某些版本中可能无法持久化
4	ImportStills([filePaths])	✅	导入 DRX 静止文件（需要 Color 页面）
5	ExportStills([stills], folderPath, prefix, format)	✅	将静止图像及其配套的 .drx 分级文件导出。需要打开带有 Gallery 面板的 Color 页面。支持格式：dpx、cin、tif、jpg、png、ppm、bmp、xpm、drx。
6	DeleteStills([galleryStill])	✅	从相册中删除静止图像

注释（v2.0.8 及以上版本）： 复合服务器的 gallery_stills 工具包含 grab_and_export 操作，可将 GrabStill() 和 ExportStills() 合并为一次调用——相比分别调用更可靠，因为它会保持实时的 GalleryStill 引用。返回导出文件列表（图像 + .drx 分级数据）。需要打开带有 Gallery 面板的 Color 页面。

图表

序号	方法	状态	测试结果/备注
1	GetNumNodes()	✅	返回节点数量（通过 ColorGroup 的前置和后置图）
2	SetLUT(nodeIndex, lutPath)	✅	在节点上设置 LUT
3	GetLUT(nodeIndex)	✅	返回 LUT 路径
4	SetNodeCacheMode(nodeIndex, cache_value)	✅	返回 True
5	GetNodeCacheMode(nodeIndex)	✅	返回 -1（未设置缓存模式）
6	GetNodeLabel(nodeIndex)	✅	返回节点标签字符串
7	GetToolsInNode(nodeIndex)	✅	返回 None（节点中无 OFX 工具）
8	SetNodeEnabled(nodeIndex, isEnabled)	✅	返回 True
9	ApplyGradeFromDRX(path, gradeMode)	✅	从 DRX 文件应用调色
10	ApplyArriCdlLut()	✅	应用 ARRI CDL LUT
11	ResetAllGrades()	✅	重置所有调色

ColorGroup

序号	方法	状态	测试结果/备注
1	GetName()	✅	返回组名
2	SetName(groupName)	✅	设置组名
3	GetClipsInTimeline(timeline)	✅	返回组中的片段
4	GetPreClipNodeGraph()	✅	返回 Graph 对象
5	GetPostClipNodeGraph()	✅	返回 Graph 对象

---

贡献说明

我们欢迎各位的贡献！以下领域尤其需要帮助：

寻求帮助：未测试的 API 方法

仍有 5 个方法（占总数的 1.5%）尚未在实际运行的 DaVinci Resolve 实例中进行测试。如果您拥有所需的基础设施或素材，欢迎提交包含测试确认的 PR：

1. 云项目相关方法（4 个方法）—— 需要 DaVinci Resolve 云基础设施：

   • ProjectManager.CreateCloudProject
   • ProjectManager.LoadCloudProject
   • ProjectManager.ImportCloudProject
   • ProjectManager.RestoreCloudProject

2. HDR 分析（1 个方法）—— 需要特定内容：

   • Timeline.AnalyzeDolbyVision — 需要 HDR/Dolby Vision 内容

如何贡献

1. 克隆仓库并创建分支
2. 创建功能分支 (git checkout -b feature/my-contribution)
3. 运行现有测试套件以确保不会引入问题
4. 添加您的测试结果或修复代码
5. 提交拉取请求

其他贡献建议

• Windows 测试 — 所有测试均在 macOS 上完成；欢迎 Windows 平台验证
• Linux 测试 — DaVinci Resolve 支持 Linux；亟需增加测试覆盖率
• Resolve 版本兼容性 — 建议在 Resolve 18.x、19.0 或更高版本上进行测试
• Bug 报告 — 如果工具在您的环境中返回意外结果，请提交问题
• 文档改进 — 完善示例、添加教程、翻译文档

平台支持

平台	状态	Resolve 路径自动检测	备注
macOS	✅ 已测试	/Library/Application Support/Blackmagic Design/...	主要开发与测试平台
Windows	✅ 支持	C:\ProgramData\Blackmagic Design\...	社区已测试；欢迎提交 PR
Linux	⚠️ 实验性	/opt/resolve/...	应该可行——欢迎测试与反馈

安全考量

本 MCP 服务器通过 DaVinci Resolve 的脚本 API 控制软件。部分工具执行的操作具有破坏性，或会与主机文件系统交互：

工具	风险	缓解措施
quit_app / restart_app	终止 Resolve 进程——若存在未保存的更改或正在进行渲染，可能导致数据丢失	MCP 客户端应在调用这些工具前要求用户明确确认。子进程调用使用硬编码命令列表，不存在 shell 注入风险。
export_layout_preset / import_layout_preset / delete_layout_preset	读取、写入或删除 Resolve 布局预设目录中的文件	路径遍历防护机制可确保所有解析后的路径仅限于预期的预设目录内（v2.0.7 及以上版本）。
save_project	在系统临时目录中创建和删除一个临时 .drp 文件	路径由服务器端生成，不涉及任何由 LLM 控制的输入。

针对 MCP 客户端开发者的建议：

• 为破坏性工具（如 quit_app、restart_app、delete_layout_preset）启用工具调用确认提示
• 不应授予此服务器中所有工具的默认自动批准权限

项目结构

davinci-resolve-mcp/
├── install.py                    # 通用安装程序（macOS/Windows/Linux）
├── src/
│   ├── server.py                # 复合型 MCP 服务器——27 个工具（默认）
│   ├── resolve_mcp_server.py    # 完整版 MCP 服务器——342 个工具（高级用户）
│   └── utils/                   # 平台检测、Resolve 连接辅助工具
├── tests/                       # 5 阶段实时 API 测试套件（319/319 通过）
├── docs/
│   └── resolve_scripting_api.txt # 官方 Resolve 脚本 API 参考文档
└── examples/                    # 入门指南、标记点、媒体、时间线示例

许可证

MIT

作者

Samuel Gursky (samgursky@gmail.com)

• GitHub: github.com/samuelgursky

致谢

• Blackmagic Design 提供了 DaVinci Resolve 及其脚本 API
• Model Context Protocol 团队促成了 AI 助手集成
• Anthropic 提供的 Claude Code 在开发和测试中发挥了重要作用

DaVinci Resolve MCP 快速上手指南

本指南帮助开发者将 AI 助手（如 Claude、Cursor、Windsurf 等）连接到 DaVinci Resolve，通过自然语言控制后期制作流程。

环境准备

在开始之前，请确保满足以下系统和软件要求：

• DaVinci Resolve Studio: 版本 18.5+ (macOS, Windows, 或 Linux)。
  • ⚠️ 注意：免费版（Free Edition）不支持外部脚本功能，必须使用 Studio 版。
• Python: 推荐版本 3.10 – 3.12。
  • ⚠️ Python 3.13+ 可能与 Resolve 的脚本库存在 ABI 兼容性问题。
• Resolve 设置:
  1. 启动 DaVinci Resolve。
  2. 进入 Preferences (偏好设置) > General (常规)。
  3. 将 External scripting using (外部脚本使用方式) 设置为 Local。

安装步骤

该工具提供通用安装脚本，可自动检测平台、配置虚拟环境并注册 MCP 客户端。

1. 克隆仓库

   git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
   cd davinci-resolve-mcp
   

2. 运行安装脚本 确保 DaVinci Resolve 正在运行，然后执行：

   python install.py
   

   脚本将自动完成以下操作：

   • 创建 Python 虚拟环境。
   • 定位 DaVinci Resolve 安装路径。
   • 配置支持的 MCP 客户端（如 Cursor, Claude Desktop, Windsurf 等）。

   常用安装选项：

   # 交互式选择客户端
   python install.py
   
   # 配置所有支持的客户端
   python install.py --clients all
   
   # 仅配置特定客户端 (例如 Cursor 和 Claude Desktop)
   python install.py --clients cursor,claude-desktop
   
   # 仅打印配置代码，不自动写入 (手动配置用)
   python install.py --clients manual
   

基本使用

安装完成后，重启你的 AI 编辑器或聊天客户端即可开始使用。

1. 验证连接

在支持 MCP 的 AI 助手对话框中，尝试发送以下自然语言指令：

当前运行的 DaVinci Resolve 版本是多少？

2. 项目与时间线操作

你可以直接指挥 AI 管理项目和剪辑：

列出所有项目，并打开名为 "My Film" 的项目。
创建一个名为 "Assembly Cut" 的新时间线，并将媒体池中的所有片段添加进去。

3. 高级功能示例

利用 v2.1.0 新增的 Fusion 节点图控制或调色功能：

在当前 Fusion 合成中添加一个 TextPlus 节点，并将其连接到 Merge 节点。
为当前选中的片段应用蓝色标记。

服务器模式说明

默认安装使用 Compound 模式（26 个复合工具），适合大多数用户，上下文占用低且响应快。 如需使用包含 342 个独立工具的 Full 模式（适合高级开发者），可在启动时指定：

python src/server.py --full

或在 MCP 配置文件中将命令指向 src/resolve_mcp_server.py。