DaVinci Resolve MCP Server

DaVinci Resolve MCP 服务

English | 简体中文

一个模型上下文协议（MCP）服务，可让 AI 助手通过官方脚本 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") 会拒绝外部进程，无论偏好设置如何。 在 Resolve 21.0.x 中，Workspace ▸ Scripts 菜单未受限制——从该菜单启动的脚本会获得实时的 resolve 对象（在免费版 21.0.3.7 中测得）—— 因此，服务可以通过一个在 Resolve 内部运行的小型脚本访问免费版，并通过经过身份验证的环回监听器重新导出该对象。**Resolve 21.1 将 Python 脚本功能移至 Studio 版。**在免费版 21.1 中，Scripts 菜单不再列出 .py 文件（Fedora 44 上的 #203 报告了此问题；同一文件夹中的 Lua 脚本 则正常列出）。尚未确认 Console 是否仍可在此运行 Python，因此 在完成实测前，请将桥接视为适用于 21.0.x 的方案。

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

安装程序和 MCP 客户端默认使用 ~/.config/davinci-resolve-mcp/bridge.json。 如需将经过身份验证的桥接配置保存在其他位置，请在运行安装程序时以及在 MCP 客户端环境中设置 DAVINCI_RESOLVE_BRIDGE_CONFIG；两端都会使用该路径。

监听器运行后，每当外部脚本不可用时，都会自动使用它——无需设置环境变量。设置 DAVINCI_RESOLVE_BRIDGE=1 则会强制使用桥接：它会成为唯一尝试的传输方式，因此如果桥接停止响应，会报告桥接自身的故障，而不会悄悄回退到其他传输方式。仅在你打算依赖桥接时使用此设置。

在 macOS 上，Resolve 只会在两个确切位置查找 Python 3：先查找 PYTHON3HOME 环境变量，再查找 /usr/local/bin/python3。Homebrew、pyenv、uv 和 conda 安装的 Python 都不在这两个位置，因此脚本不会出现在菜单中，而且不会显示任何提示。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”和文件夹路径错误。

有两件事容易出问题（#182）。前缀必须同时包含 lib/libpython3.X.dylib 和 bin/python3，且后者必须使用完全一致的无版本号名称——Homebrew 的框架构建通常只提供 bin/python3.13，对 Resolve 来说这相当于只有半套 Python；安装程序的预检现在会指出这一点，而不是将该前缀报告为可用。还有，launchctl setenv 重启后不会保留；如果几周后脚本不再列出，且没有任何错误提示，原因就在这里。若要让设置持久生效，可以将解释器放到 Resolve 已经会查找的位置（这需要 sudo，并请检查 /usr/local/bin 在 PATH 中是否排在你常用的 Python 之前）：

sudo ln -s "$(command -v python3)" /usr/local/bin/python3

已在 macOS 上的免费版 21.0.3.7 和 Studio 19.1.3.7 中验证。v2.70.1 中添加的 Windows 路径（问题 #106）发布时未经验证；此后，免费版 21.0.1.11（问题 #109）和免费版 21.0.3.7（问题 #112）的报告显示，在 Windows 11 上，桥接可从 %PROGRAMDATA% 和 %APPDATA% 两处安装、列出并提供服务，因此这些路径如今已得到确认，而非仅仅假设。Linux 也已确认：免费版 20.3.2.9（问题 #129，Fedora 43）的报告显示，桥接已安装到 ~/.local/share/DaVinciResolve/Fusion/Scripts/Utility，使用系统 Python 列出脚本——Linux 没有这类发现问题——并完成端到端服务。现在没有任何平台的支持仅依赖假设：macOS 已直接验证，Windows 和 Linux 则有用户报告佐证。

请注意，桥接在提供服务期间会一直占用其端口。v2.70.3 之前的 Windows 桥接进程可能在 Resolve 退出后仍继续运行，从而占用下一个会话的监听端口；如果你使用的是较旧版本，且桥接停止响应，请检查是否有过期的 fuscript.exe 仍占用该端口。

这是文档记载的应用内路径，并非规避许可限制，但 Blackmagic 可能会关闭它——请将其视为“支持期限不定”的方案。仅限环回连接、使用 HMAC 签名的请求、一次性随机数。

本地控制面板

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

venv/bin/python -m src.control_panel

该命令会启动一个仅限环回连接的服务，并在浏览器中打开控制面板。打开的 URL 携带每次启动生成的访问令牌（http://127.0.0.1:8765/#token=…）——请使用这个确切的 URL；没有令牌的请求会被面板拒绝。如需让 AI 编码 Agent 执行此操作，请这样提出请求：**“为此仓库打开 Resolve MCP 控制面板。”**除非你的 Python 环境已激活，否则 Agent 应使用 venv/bin/python -m src.control_panel。持久化的分析任务会在成功处理各个切片后自动刷新本地搜索索引；手动执行 Build Index 用于根据现有报告重建索引。

服务模式

模式	入口点	工具	最适合
复合模式	src/server.py	37	适用于大多数助手的默认模式。相关的 Resolve 操作按操作参数分组，以降低上下文用量。
完整／细粒度	src/server.py --full 或 src/resolve_mcp_server.py	390	希望每种 Resolve API 方法都对应一个 MCP 工具的高级用户。

除非你明确需要每种方法对应一个工具的细粒度接口，否则建议使用复合服务器。

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

同一软件包还附带第二个可选 MCP 服务：davinci-resolve-advanced-mcp（二进制文件 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（帧预言机 conform／重新链接 QC 及血缘追踪）、color_trace（在重新 conform 后迁移调色）、fusion、audio_plan、fairlight（总线路由）、audio、project_read、project_db、pipeline （以数据库为准的管线：将 YAML 项目规范编译为规范化 SQLite 数据库，然后通过关卡、来源信息和意图↔实际偏差检测来运行各个阶段）、capabilities、deliverable（交付物 QC／合规性）、media（媒体前端／AE 导入）、editorial（剪辑完整性／变更列表）、provenance（来源信息／审计／剧集报告）。它也可以作为库使用（可导入的引擎 API），而不仅仅是作为服务器启动。

DRX 调色写入经过 Resolve Studio 实时校准：调色参数默认采用 Resolve 屏幕面板单位（space: 'ui' | 'drx'），结构性写入（Power Window、限定器、HDR 区域、HSL 曲线、ColorSlice、模糊／键控／运动效果）均通过面板回读验证——各控件的状态见 resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md。它还弥补了一个仅限 UI 的缺口：程序化“Cleanup Node Graph”（针对单个片段使用 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 会打印两个入口。核心采用纯 JavaScript／MIT 许可，无需原生模块；少数功能需要用户安装的工具（audio 需要 ffmpeg，部分路径需要 sharp／better-sqlite3）——调用 capabilities 工具即可查看实时状态和安装提示。

与 Python 服务不同，此服务依赖 Node。npx davinci-resolve-mcp setup 会将依赖项安装到受管理的安装目录中（在 resolve-advanced/ 下运行 npm install --omit=dev --omit=optional），然后才注册二进制文件。如果安装无法运行（例如处于离线状态或 npm 不可用），setup 会改为注册高级服务器的 npx 命令，因此写入的入口始终可以启动。无需重新运行 setup，即可修复现有安装：npx davinci-resolve-mcp sync。

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

维护者还基于这一开放基础打造了 Bradford Post Assistant，这是一款桌面应用。MCP 服务为 Agent 提供操作能力，而 Post Assistant 则是围绕这些服务运行的工作助手——一款用于后期制作的本地 AI 助手，客户素材始终留在工作站上：

• 后期制作助手——一款与 DaVinci Resolve 并行运行的桌面应用，可实时监控会话（时间线、调色和画面，而不仅是 API 调用），内置 AI 助手和 Agent 运行时，支持本地媒体分析（转录、画面分析、剪辑智能分析）以及应用内合片 QC。
• 记忆——持久化且加密的本地助手记忆，以及从管线解码出的事实中挖掘的跨剧集学习成果（季级视觉风格偏移、每台摄像机的校正先验、关键帧库、合片路径映射复用）；系统会为你管理积累过程，并提供洞察审核工作流。
• 专为独立运行而设计——Post Assistant 会自行连接所有组件：用于控制 Resolve 的此 MCP、提供扩展服务的 Bradford API，以及你选择的大模型提供商。无需手动配置，无需管理单独的客户端；应用还会通过经过签名的自动更新，让自身（以及捆绑的 MCP）保持最新。
• 扩展的专业工具集——通过托管的 Bradford API 提供实时项目调色修复、22+ 种自适应调色系列、精选视觉风格库、交付规格验证、剪辑节奏与清理分析、自然语言色彩指导，以及 Fusion 合成创作。
• 制作工作流——将原始工具组合为完整的实际工作流程（交接 → 合片 → 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"

核心能力

领域	复合服务支持的功能
应用和项目控制	启动／重新连接、页面切换、项目增删改查、项目文件夹、数据库、云项目封装、设置、预设、归档
媒体池和导入	安全导入、图像序列、多机位准备时间线、素材箱整理、元数据规范化、元数据字段清单、标记、注释、重新链接／代理／全分辨率保护
媒体分析	安全分析源文件／片段／素材箱／项目、2-pop／场记板拍手同步事件检测、默认写回 Resolve 元数据和媒体池标记、持久化分析产物、复用现有报告、host_chat_paths 视觉分析（通过 commit_vision 按片段最终确认，适用于任何具备视觉能力的 MCP 客户端），并可选择退出；转录，并可选择退出
时间线编辑和整理	轨道／项目探查、标题文本键扫描／写入、复制／移动／重复辅助、波纹插入、范围操作、间隙／重叠、源范围、经检查的交换格式导出／导入
审阅注释	时间线／项目／片段标记、自定义数据、标志、片段颜色、复制／移动／同步清理、审阅报告、标记缩略图审阅
色彩和调色	节点图探查、CDL 验证、调色复制、DRX／LUT 辅助、版本、Gallery 静帧、色彩组
Fusion	时间线项目合成、安全创建工具、输入写入、端口检查、经过验证的连接、限定范围的批量写入
音频和 Fairlight	轨道／项目探查、源映射、受保护的音频属性写入、人声隔离、自动同步规划、转录／字幕探查
渲染和交付	格式／编解码器矩阵探查、渲染设置验证、队列作业生命周期检查、受保护的快速导出
扩展编写	Fuse、DCTL、ACES DCTL 以及 Resolve 页面 Lua／Python 脚本生命周期辅助功能，支持安全的 MCP 标记安装／移除
创作指南	捆绑的剪辑、色彩、音频和工作流指南以 MCP 上的文字形式提供，可供任何客户端索引、搜索和阅读，而不仅限于磁盘上存有此仓库的客户端

操作封装

每个复合工具的返回值都会在负载旁携带一个 _operation 块，因此 Agent 读取的是统一结构，而不是每个工具都使用不同的键：status （success／partial／blocked／failed）、verification（其中 contradiction 单独区分，表示 Resolve 报告成功，但回读结果与之不符）、changes （语义变更）、warnings 和 execution_id。

有两种缺失情况具有明确含义，且是有意为之。verification.status: "unverified" 表示没有报告证据，而不是“已检查且无问题”。缺少 changes 表示该操作没有报告变更，而不是没有发生变化——如果在此处返回空的 {}，就等于对一个根本没有声明变更的编辑作出自信却错误的回答。

此封装采用命名空间，而非合并到顶层，因为 status、operation、warnings、result 和 changes 都已经是此处的领域 键；扁平化会改写后台作业的 status: "done" 和确认门的 status: "confirmation_required"。setup(action="set_defaults", params={"result_envelope": "pure" | "legacy"}) 可更改结构，也可通过每次调用时设置 params={"envelope": ...} 或按进程设置 RESOLVE_MCP_RESULT_ENVELOPE 来更改。

Agent 执行跟踪（“编辑器为什么这么做？”）

多步 AI 操作会将多个工具调用关联起来，形成统一的执行跟踪。每条跟踪汇总工具耗时（duration_ms）、调用次数、累计语义变更（items_deleted、items_added）和回读验证。Agent 和编辑器可以通过 resolve_control 检查工作流：get_execution_trace(execution_id?)、list_recent_executions()，或通过 begin_execution(request="...") / end_execution() 开启一个限定范围的执行。export_execution_report(execution_id?, format="markdown"|"json") 会生成可供审查的审计文件，包含相同的摘要，默认写入 logs/execution-reports/<execution_id>.md。你也可以通过 path 将它写入任意位置——例如，放在按日期命名的 TransferFiles 文件夹中的 conform 文件旁边——系统会创建所需目录，因此发送前请检查路径。除非设置 overwrite: true，否则不会覆盖已有文件。inspect_operation(tool?, target_action?, target_params?) 会在执行操作前评估预检风险等级（low、medium、high、critical）、破坏性可能和影响范围（item、track、timeline、project、system）；list_lifecycle_hooks() 则用于检查活跃的执行拦截器。

它是基于操作名称的启发式判断，并非模拟操作——它不会触及项目，也不会验证参数，因此 recognised: false 表示使用的是默认等级，而不是发现了问题；snapshot_available: null 表示尚未确定是否可以回滚，而非无法回滚。所有随附的 hook 都只进行观察；没有任何 hook 会替换工具的结果，因此 dry_run 始终会到达真正的处理程序，而对于本身不提供预览的操作，也不会合成预览。

对于没有任何验证记录的运行，报告会写明 “尚未确定——没有记录检查”，而不是“已通过”。证据缺失意味着问题仍未解决；审计文档尤其不该让读者将其误读为一切正常。

跟踪记录保存在包含 100 条记录的内存环形缓冲区中，并附加写入 server.log 旁边的 logs/execution-traces.jsonl——RESOLVE_MCP_TRACE_FILE 可更改其位置，RESOLVE_MCP_LOG_FILE 可更改 server.log 本身的位置（可指定路径，或留空以不写入文件；离线测试套件会将其指向临时文件，因此不会写入操作员的日志）。list_recent_executions 会报告该路径及其是否可写，因此无需读取源代码，就能区分“日志为空”和“没有写入任何内容”。记录的内容包括工具名称、操作、时间、状态、语义变更和验证——不包括参数和文件路径。唯一的自由文本字段是你传给 begin_execution 的 request，因此请像撰写客户端项目的提交消息一样谨慎填写。

已验证陷阱防护

src/utils/api_truth.py 记录了通过实测 Resolve 正在运行的构建得出的 Resolve API 行为，而非从函数签名中读取的行为——那些调用虽然什么都没做却返回 True、被静默拒绝的设置键，以及根本不存在的方法。过去，这份记录只能主动查询：它会响应 resolve_control(action="api_truth")，除此之外，就只是一份在工作过程中没人会去搜索的文件。

现在，相关信息会在调用点传达给调用方。映射到某个已记录事实的操作，其结果会附带一条简洁的 known_limitation——包含符号、实际行为、建议，别无其他；因为长时间评分期间，响应大小确实会带来成本，而完整条目只需一次查询即可获取。

只有当映射中列出的正是那个符号时，才会附加事实。不会根据相似名称推断：把无关说明贴到失败信息上，会让人误以为这是诊断结果；错误的诊断比没有诊断更糟。

有一种行为会直接拒绝，而不是发出警告。 TimelineItem.CopyGrades 会完全替换目标的调色数据——通过将每种状态烘焙为 33 点 LUT 并比较字节来实测——替换时仍会返回 True，而且不会创建可供回退的版本。将其用于包含手工调色成果的片段，会造成无法恢复的损失，却报告操作成功。因此，在调用方传入 acknowledge_trap: true 之前，调用该方法的操作都会被拒绝：

{
  "success": false,
  "error": "'timeline_item_color.copy_grades' is refused: its verified behaviour destroys existing work that cannot be recovered afterwards.",
  "known_limitation": [{"symbol": "TimelineItem.CopyGrades", "reality": "...", "recommended": "..."}],
  "retry_with": {"acknowledge_trap": true}
}

目的不是禁止此操作，而是让调用方明确表示自己知道它的实际行为。试运行不受此限制：预览不会破坏任何内容。

设置 RESOLVE_MCP_DISABLE_TRAP_GUARD=1 可关闭拒绝机制和提示信息。对于以前收到简单 {"success": true}、但执行了破坏性复制的调用方，这属于行为变更。

支持拒绝机制的事实必须能够重新测量，因此实时探测会重新推导每一项事实，并在 Resolve 不再符合记录时标记为 drifted；如果某个 destroys_prior_work 条目没有探测，对应测试就会失败。

可选附加项

核心安装刻意保持精简：Python、ffmpeg 和 Resolve 脚本 API。某些功能需要更多组件，而且每项功能都会如实拒绝执行，并提供各自的安装命令，而不是退化成猜测——伪造的节奏或虚构的音量会产生看似可信却错误的输出，这比没有该功能更糟。

运行 python scripts/doctor.py，查看你已安装的组件。

附加项	解锁的功能	许可证
PATH 中的 ffmpeg	静音检测、空白片段标记、音量测量、音频分析。最值得安装的单项工具。	LGPL/GPL — 以子进程方式调用，从不捆绑
pip install numpy	色彩预平衡、参考静帧匹配、声音密度审计	BSD
pip install librosa	面向音乐剪辑的节拍、小节和乐句检测	ISC
pip install -U openai-whisper	转录，以及基于词级内容构建的所有功能	MIT
pip install open_clip_torch	视觉相似度和 find_similar	MIT
pip install transformers	CLAP 音频嵌入	Apache-2.0
pip install opencv-python	额外的帧分析	Apache-2.0

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

这里的内容都不会被捆绑。 模型权重有各自独立于加载代码的许可证；商业使用前请先确认。

不做什么

了解工具的能力边界与了解它能做什么同样重要；在这里读完，比在项目进行中才发现要省事。

不支持的功能	原因及替代方案
选择最佳录制版本	表演效果是判断录制版本是否合适的主要依据，但无法从波形或转录文本中衡量。rank_takes 评估的是流畅度——填充词、重新起头、脚本覆盖情况——并会在每次响应中说明这一点。实际播放的录制版本往往是最不流畅的，因为犹豫常常正是表演的一部分。可以用它来找出干净的备用版本，但不要用它来决定采用哪种演绎。
自动编辑音乐	可选的 librosa 支持提供节拍检测和节拍／小节／乐句剪辑点计划，不会生成完整的成片。强拍位置根据第一个节拍推断；对于弱起，请使用 beat_offset。语音静音工具不适合查找音乐剪辑点。
判断剪辑效果	这里没有任何功能能判断某次剪辑是否合适。因此，所有破坏性操作都遵循“计划 → 审核 → 确认”的流程。
取代剪辑软件	输出是初步组装版本，类似助理剪辑师的工作：导入、同步、整理、串接、标记问题。这是供你继续剪辑的起点，不是成片。默认设置刻意宽松——初步组装版本理应较长，因为删减快速且一目了然，而恢复已丢弃的素材既耗时又不易察觉。
修改源媒体	这是设计要求，没有例外——详见下文。

对于已经分析但无法核实的内容，都会标记为未核实，绝不会将其归入“正常”。空结果表示“未发现任何内容”，绝不表示“无内容可查”。

源媒体安全

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

安全态势

默认服务是由 MCP 客户端启动的本地 stdio 进程；它不会开放网络监听端口，也没有内置的多用户身份验证界面。两个可选的本地 HTTP 接口——控制面板和联网 MCP 传输——仅绑定到回环地址，并且每个请求都必须携带每次启动时生成的 Bearer 令牌；同时还会通过 Host／Origin 检查防范 DNS 重绑定和 CSRF。工具元数据包含面向 MCP 客户端的安全提示，涵盖只读、破坏性、幂等和外部资源操作。两种服务上的破坏性写入都会遵循 destructive.safe_mode 并记录在安全审计日志中；只有复合服务会在修改时间线前将其存档——细粒度写入要么被拒绝，要么被记录，绝不会被恢复。有关操作边界、确认指南和漏洞报告方式，请参阅 安全政策。

关键统计

指标	数值
MCP 工具	37 个复合工具 / 390 个细粒度工具（在线服务）
高级（离线）工具	18 个 — .drp/.drt/.drx 和数据库创作，无需运行 Resolve
内核操作	9 个复合工具涵盖 136 项受保护的工作流操作
API 方法覆盖	361/361（100%）
实时测试的方法	338/361（93.6%）
实时测试通过率	338/338（100%）
测试环境	DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio + Resolve 21.0.3 free（通过应用内桥接）

如需查看逐项方法的状态，请参阅 API 覆盖与测试结果。如需了解当前的工作流支持情况，请参阅 内核操作覆盖范围。

analyze_media 默认直接执行，将可检查的报告和产物保存在分析根目录下，通过 host_chat_paths 协议请求主机聊天进行视觉分析（analyze 会返回绝对帧路径和 JSON 架构；主机聊天将每帧作为图像读取，并调用 media_analysis(action="commit_vision", ...) 完成分析），通过配置的本地后端运行转录，并将分析摘要以及源时间 Media Pool 片段标记写回 Resolve 项目。只有在想要停用这些默认行为时，才传入 include_visuals=false、include_transcription=false、publish_metadata=false、timed_markers=no 或 dry_run=true。跳过 commit_vision 会使此次运行停留在 pending_host_vision_analysis 状态——这会作为故障模式显式呈现，不会被静默降级。

文档

文档	用途
安装与配置	要求、安装程序选项、支持的客户端、服务模式、手动配置
API 覆盖范围与测试结果	关键统计数据、API 覆盖范围表、实时测试状态、完整方法参考
内核操作覆盖范围	当前受保护的工作流操作映射
AI 技能参考	使用复合服务的 AI 助手所需的操作上下文
控制面板指南	本地浏览器面板概览：概览、审核（bin/clip/shot）、分析、设置、偏好设置
媒体分析指南	安全处理源文件的 FFprobe、FFmpeg、Whisper、sidecar 和分析根目录工作流
多机位设置助手指南	堆叠时间线准备、助手/API 边界以及 Resolve UI 转换步骤
编辑决策指南	项目自有的编辑创作指导，适用于分析和时间线决策
整理 Avid AAF	为什么所有三种 Resolve 原生方案在整合后的交付项目中都会失败，以及哪一种方案有危险
原生 .drt 编写	离线模板拼接时间线编写：剪辑、变速、转场、淡入淡出、标记、复合片段，以及经测量验证的规则
无头编辑循环	从命令行驱动 Resolve：哪些交换格式可重新链接并往返转换，以及在 GUI 和 -nogui 中的测量结果
色彩决策指南	项目自有的色彩校正指导和 Resolve 色彩 API 边界
贡献指南与项目布局	贡献工作流、平台支持、安全说明、代码库结构
安全策略	本地 stdio 信任边界、工具元数据、确认指引、问题报告
发布流程	维护者发布检查清单、版本位置、验证、标签和发布说明
变更日志	历史发布说明

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

要求

• macOS、Windows 或 Linux 上的 DaVinci Resolve 18.5+。Studio 版原生支持外部脚本。免费版不支持——Blackmagic 将外部脚本功能限制为 Studio 版；但仍可通过应用内桥接访问，该桥接在 Resolve 内运行，可通过未受限制的 Workspace ▸ Scripts 菜单启动。
• Python 3.10+（风险最低的范围是 3.10-3.12）。较新的 Resolve 版本也支持 Python 3.13/3.14（已在 Studio 20.3.2 上验证）；旧版本可能无法连接 3.13+，此时请使用 3.10-3.12。
• 无法连接？运行 python3 scripts/doctor.py，即可检查服务使用的 Python，并针对每个问题打印确切的修复方法：32 位或架构不匹配的 Python、版本高于 Resolve 版本支持范围的 Python，或存在多个 Python 时 MCP 客户端启动了错误的版本。请参阅检查 Python 环境。
• 将 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 提供的原因，而不会自行猜测。

报告 Bug 和请求功能

告诉助手“将此作为 bug 提交”或“将此作为功能请求提交”。它会根据对话起草 GitHub issue，其中包含失败的调用及其错误，并附上服务版本、Resolve 版本、连接模式和操作系统。本地路径、用户名以及任何看起来像机密的内容都会被隐去。系统不会代你提交：你会获得一个预填好的链接，审核草稿后自行在 GitHub 上提交。你也可以直接创建 issue。

开发

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 Agent 应从 AGENTS.md 开始；Claude Code 用户也可以阅读 CLAUDE.md，其中指向相同的权威说明。

许可证

MIT

作者

Samuel Gursky ([email protected])

• GitHub：github.com/samuelgursky

致谢

• 感谢 Blackmagic Design 提供 DaVinci Resolve 及其脚本 API
• 感谢 Model Context Protocol 团队让 AI 助手集成成为可能