DaVinci Resolve MCP Server

English | 简体中文

一个模型上下文协议（MCP）服务器，让 AI 助手能够通过官方的 Scripting API 控制 DaVinci Resolve Studio。它提供完整的 API 覆盖，并附带受保护的工作流助手，用于剪辑、媒体池管理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发以及源安全媒体分析。

服务器附带一个本地浏览器控制面板，用于检查 Resolve 状态、运行源安全分析、深入查看已分析的片段和镜头，并以内联方式编辑分析输出。完整介绍请参阅控制面板指南。

快速开始

npx davinci-resolve-mcp setup

在连接之前，请打开 DaVinci Resolve Studio，并将 Preferences > General > External scripting using 设置为 Local。（在免费版上，该偏好设置无效——请参阅下面的免费版。）npm 启动器会在你的用户应用程序数据目录下安装一份受管副本，然后运行通用 Python 安装程序。该安装程序会创建虚拟环境、检测 Resolve 路径，并可配置 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Zed、Continue、Cline、Roo Code、OpenCode、Codex CLI 和 JetBrains IDE。

对于源码安装：

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

有关平台路径、客户端特定配置和手动设置，请参阅安装与配置。

安装程序和服务器会检查 GitHub 上的最新版本以获取 MCP 更新。检查是尽力而为且受速率限制的；服务器绝不会因提示而阻塞 MCP 启动。安装程序可以提示、稍后提醒、忽略某个版本、禁用检查，或对干净的 git 检出应用可选的安全自动更新。

免费版（应用内桥接）

Blackmagic 将外部脚本限制为仅限 Studio：在免费版上 scriptapp("Resolve") 会拒绝外部进程，无论偏好设置如何。Workspace ▸ Scripts 菜单不受限制——从该菜单启动的脚本在任何版本上都能获得实时的 resolve 对象——因此服务器可以通过一个在 Resolve 内部运行的小脚本访问免费版，并通过经过身份验证的回环监听器重新导出该对象。

python scripts/install_resolve_bridge.py
# restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge

一旦该监听器运行，每当外部脚本不可用时就会自动使用它——无需环境变量。设置 DAVINCI_RESOLVE_BRIDGE=1 会强制使用桥接：它成为唯一尝试的传输方式，因此停止响应的桥接会报告自身的故障，而不是悄然回退到另一种传输方式。当你打算依赖桥接这一路径时，请使用该变量。

在 macOS 上，Resolve 只会在两个位置查找 Python 3：PYTHON3HOME 环境变量，然后是 /usr/local/bin/python3。Homebrew、pyenv、uv 和 conda 都不在这两个位置，因此该脚本会静默地从不显示在菜单中。python.org 的安装可以工作，因为其安装程序会创建 /usr/local/bin/python3——但你不一定需要它：只需让 Resolve 指向你已有的解释器，无需 sudo。

launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"

请使用 launchctl setenv，而不是 export——Resolve 是从 Dock 启动的，永远不会看到你 shell 的环境。之后请重启 Resolve。同时会安装一个 Lua 金丝雀脚本，以便你将“未检测到 Python”与错误的文件夹区分开来。

已在 macOS 上的免费版 21.0.3.7 和 Studio 19.1.3.7 上验证。v2.70.1（issue #106）中添加的 Windows 路径在发布时未经核实；此后关于免费版 21.0.1.11（issue #109）和免费版 21.0.3.7（issue #112）的报告显示，桥接在 Windows 11 上从 %PROGRAMDATA% 和 %APPDATA% 两个位置安装、列出并提供服务，因此这些路径现已确认，而非假设。Linux 也已确认：一份关于免费版 20.3.2.9（issue #129，Fedora 43）的报告显示，桥接安装到 ~/.local/share/DaVinciResolve/Fusion/Scripts/Utility，并针对系统 Python 列出——Linux 没有这种发现问题——并能端到端提供服务。现在没有任何平台依赖假设：macOS 是直接验证的，Windows 和 Linux 则基于用户报告。

请注意，桥接在服务期间会一直持有其端口。在 v2.70.3 之前，Windows 桥接可能比 Resolve 存活更久，并阻塞下一会话的监听器；如果你使用的是较旧版本且桥接停止响应，请检查是否有过期的 fuscript.exe 仍然占用该端口。

这是文档化的应用内路径，并非规避许可，但 Blackmagic 可能会关闭它——请将其视为“支持到不再支持为止”的层级。仅限回环、HMAC 签名请求、一次性 nonce。

本地控制面板

从仓库根目录启动单用户本地控制面板：

venv/bin/python -m src.control_panel

该命令会启动一个 localhost 服务器并在浏览器中打开控制面板。要让 AI 编码代理执行此操作，可以请求：“打开此仓库的 Resolve MCP 控制面板。” 代理应使用 venv/bin/python -m src.control_panel，除非你的 Python 环境已经激活。持久化的分析作业会在成功切片后自动刷新本地搜索索引；手动“构建索引”操作用于从现有报告重建索引。

服务器模式

建议使用复合服务器，除非你确实需要细粒度的每方法一个工具的表面。

高级服务器 — 超越脚本 API（可选，Node）

同一个包还附带第二个可选的 MCP 服务器：davinci-resolve-advanced-mcp（bin bin/davinci-resolve-advanced-mcp.mjs）。Python 服务器通过官方认可的脚本 API 驱动实时 Resolve，而高级服务器则做 API 无法做到的事情——它读取和编辑 Resolve 文件（.drp / .drt / .drx），并在不运行 Resolve 的情况下应用数据库/XML 级别的更改，因此它可以在云端或本地运行。18 个工具：drp、drt、drx（逐片段调色编解码器外加一个确定性的离线调色/QC 目录——机内 + 跨机肤色（v2 肤色线指标）+ B-roll + 中性色卡白平衡匹配、匹配到参考、饱和度/黑平衡、对比度归一化、ASC CDL 导入、无损调色转移 + 剧集风格创作、命名 LUT 附加、示波器读取 + 意图标签、验证调色、显示参考帧提取、广播合法 QC）、offline_ref、conform（frame-oracle 套对/重新链接 QC + 谱系）、color_trace（在重新套对时携带调色）、fusion、audio_plan、fairlight（总线路由）、audio、project_read、project_db、pipeline（一个 DB 即真相管线：将 YAML 项目规格编译为规范 SQLite 数据库，然后运行带有门控、来源和意图↔实际漂移检测的阶段）、capabilities、deliverable（交付物 QC / 合规）、media（媒体前端 / AE 导入）、editorial（编辑完整性 / 变更列表）、provenance（来源 / 审计 / 剧集报告）。它也可以作为库使用（可导入的引擎 API），而不仅仅作为服务器启动。

DRX 调色写入会针对 Resolve Studio 进行实时校准：调色参数默认采用 Resolve 的屏幕面板单位（space: 'ui' | 'drx'），并且结构性写入（power windows、qualifiers、HDR zones、HSL curves、ColorSlice、blur/key/motion-effects）均经过面板回读验证——各控件的状态见 resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md。它还弥补了一个仅限 UI 的缺口：以编程方式“清理节点图”（drx relayout 用于单个片段，project_db relayout_node_graphs 用于整个项目）——节点布局得到整理，调色内容字节级保留。

将其与实时服务器一起添加（两者都随一个 npm install 提供）：

{
  "mcpServers": {
    "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
    "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
  }
}

install.py 会打印两个条目。核心是纯 JS/MIT，没有必需的原生模块；少数功能需要用户自行安装的工具（audio 需要 ffmpeg，某些路径需要 sharp/better-sqlite3）——调用 capabilities 工具可获取实时状态和安装提示。

Bradford Post Assistant — 托管应用程序（封闭测试版）

维护者还在这个开放基础之上构建了 Bradford Post Assistant，一款桌面应用程序。MCP 服务器赋予代理双手，而 Post Assistant 是围绕它们的协作副驾驶——一款面向后期制作的设备端 AI 助手，客户素材永远不会离开工作站：

• 后期制作副驾驶——一款与 DaVinci Resolve 并排运行的桌面应用，实时观察会话（时间线、调色和画面，而不仅仅是 API 调用），内置 AI 助手和代理运行时，提供本地媒体分析（转录、画面分析、编辑智能）和应用内套对 QC。

• 记忆——持久化、加密的设备端助手记忆，加上从你的管线解码事实中挖掘的跨剧集学习（剧集风格漂移、每机校正先验、主画面库、套对路径映射复用），积累由系统为你管理，并提供经过审查的洞察工作流。

• 设计上自包含——Post Assistant 自行连接所有内容：用于 Resolve 控制的此 MCP、用于其扩展服务的 Bradford API，以及你选择的 LLM 提供商。无需手动配置，无需管理单独的客户端，应用会通过签名的自动更新保持自身（及其捆绑的 MCP）为最新版本。

• 扩展的专业工具集——对实时项目进行调色手术、22 个以上自适应调色系列、精选外观库、交付规格验证、编辑节奏/清理分析、自然语言色彩指导，以及 Fusion 合成创作——通过受管的 Bradford API 交付。

• 制作工作流——将原始工具组合成完整的实际流程（交接 → 套对 → QC → 交付、剧集风格延续、剧集报告），并带有面向客户的制作机构所期望的护栏和审批流程。

目前处于封闭测试版——你可以在 bradfordoperations.com/software/post-assistant 申请访问权限。开源服务器本身是完整且全功能的。

你能做什么

"List all projects and open the one called 'My Film'"
"Create a timeline called 'Assembly Cut' from all clips in the current bin"
"Build a multicam prep timeline from selected camera angles and preserve source media"
"Detect 2-pops or slate claps and suggest record offsets for sync prep"
"Publish analysis summaries, keywords, people, and slate hints into Resolve clip metadata"
"Probe this timeline for gaps, overlaps, missing media, and source frame ranges"
"Safely import this image sequence, organize it into bins, and normalize clip metadata"
"Build a ProRes 422 HQ render plan, validate the settings, and queue the job"
"Copy review markers from the timeline to the selected clip and export a review report"
"Snapshot this clip's grade, validate a CDL update, and export a temp LUT"
"Create a Fusion TextPlus overlay on the selected clip and verify graph connections"
"Report audio channel mappings, voice isolation availability, and subtitle support"
"Install this MCP-marked DCTL or script, classify refresh/restart needs, then remove it"

核心能力

可选附加项

核心安装包有意保持精简：Python、ffmpeg 和 Resolve 脚本 API。有些功能需要更多依赖，而每个功能都会诚实地以自身的安装提示拒绝执行，而不是退化为猜测——虚构的节奏或臆造的电平会产生自信但错误的输出，这比没有该功能更糟糕。

运行 python scripts/doctor.py 查看你拥有其中哪些功能。

media_analysis 操作的 capabilities 会详细报告分析栈，并说明每个缺失组件能启用哪些功能。

这里没有任何内容是捆绑分发的。 模型权重自带与加载代码分离的许可证；商业使用前请检查。

本工具不做什么

了解工具的边界与了解其功能同样重要，而且在这里了解比在项目中途发现更省成本。

任何已分析但无法验证的内容都会报告为未验证，绝不会归入“正常”。空结果意味着“未找到”，而不是“没有可找的”。

源媒体安全

本项目将摄影机原始素材和源媒体视为不可变数据。分析工具仅读取源文件，并将报告写入附属文件、临时目录或项目分析目录；确认后的元数据发布仅写入 Resolve 的项目数据库。除非用户明确要求，服务器不得修改、转码、代理或创建源媒体的衍生内容。详细的源安全工作流程请参阅 媒体分析指南。

安全态势

默认服务器是一个由你的 MCP 客户端启动的本地 stdio 进程；它不暴露网络监听器或内置的多用户认证界面。工具元数据包含 MCP 客户端安全提示，用于只读、破坏性、幂等和外部资源操作。操作边界、确认指南和漏洞报告请参阅 安全策略。

关键指标

关于逐方法的状态，请参阅 API 覆盖与测试结果。关于当前工作流支持，请参阅 内核操作覆盖。

analyze_media 默认直接执行，将可检查的报告/工件持久化到分析根目录下，通过 host_chat_paths 协议请求主机聊天视觉分析（analyze 返回绝对帧路径 + JSON 模式；主机聊天将每一帧作为图像读取，并调用 media_analysis(action="commit_vision", ...) 来完成），通过配置的本地后端运行转录，并将分析摘要以及源时间媒体池剪辑标记写回 Resolve 项目。仅在您希望退出这些默认行为时，才传递 include_visuals=false、include_transcription=false、publish_metadata=false、timed_markers=no 或 dry_run=true。跳过 commit_vision 会使运行停留在 pending_host_vision_analysis — 这被作为失败模式呈现，而不是静默降级。

文档

扩展编写参考位于 docs/authoring 中。Resolve 开发者包说明位于 docs/notes 和 docs/integrations 中。提示词配方位于 examples 中。

要求

• macOS、Windows 或 Linux 上的 DaVinci Resolve 18.5+。Studio 直接支持外部脚本。免费版 不支持 — Blackmagic 将外部脚本限制为 Studio — 但通过 应用内桥接 仍然可以访问，该桥接从无限制的 Workspace ▸ Scripts 菜单在 Resolve 内部运行。

• Python 3.10+（3.10-3.12 是风险最低的范围）。Python 3.13/3.14 也可在最近的 Resolve 构建上运行（已在 Studio 20.3.2 上验证）；较旧的构建可能无法在 3.13+ 上连接，在这种情况下请使用 3.10-3.12。

• 将 Resolve 外部脚本设置为 Local（Studio）。在免费版上，此 偏好设置无效 — 请改用 应用内桥接 代替。

Resolve 19.1.3 仍然是兼容性基线。Resolve 20.x 的脚本调用是增量式的、受版本保护，并在 20.3.2 上进行了实时测试。Resolve 21.0 的脚本新增功能（音频分类、说话人检测转录、IntelliSearch、场记板分析、运动去模糊、语音生成、会话后台任务控制）通过运行时能力检测来暴露，因此它们在较旧的构建上保持惰性，并在 Resolve 21+ 上自动激活。它们已在 Studio 21.0.2.4 上进行了实时测试 — 请参阅 Resolve 21 增量变化。请注意，AnalyzeForIntellisearch、AnalyzeForSlate 和 GenerateSpeech 都需要单独下载的 AI Extras 包，而 Resolve 对于缺失包的报告不一致（有些返回 False，有些返回错误字符串），因此这些操作会报告 success: false，并附带 Resolve 提供的原因，而不是进行猜测。

开发

python src/server.py          # Compound server
python src/server.py --full   # Granular server
venv/bin/python tests/test_import.py
venv/bin/python scripts/audit_api_parity.py

发布和验证规则位于 docs/process/release-process.md。在此仓库中工作的 AI 代理应从 AGENTS.md 开始；Claude Code 用户也可以阅读 CLAUDE.md，该文件指向相同的规范说明。

许可证

MIT

作者

Samuel Gursky (samgursky@gmail.com)

• GitHub: github.com/samuelgursky

致谢

• 感谢 Blackmagic Design 提供 DaVinci Resolve 及其脚本 API

• 感谢 Model Context Protocol 团队实现 AI 助手集成