DaVinci Resolve Lua MCP

DaVinci Resolve Lua MCP

通过在 Resolve 内运行的 Lua 脚本，让 Claude 控制免费版 DaVinci Resolve 21.1。支持 macOS 和 Windows（实验性），无需 Studio 许可证，也无需网络。

DaVinci Resolve 21.1 将 Python 脚本和外部脚本 API 移到了 Studio 版，Blackmagic 自带的 MCP 服务也仅随 Studio 版提供。免费版仍有一扇门敞开：Workspace > Scripts 会列出并运行 Lua 文件。本项目会在此处放置一个小型 Lua 脚本。每次启动 Resolve 会话时运行一次，它会持有实时的 resolve 对象，并代表 MCP 服务执行 Lua。Claude Desktop 会将该服务作为扩展运行。

说明

这里的任何内容都不会解锁 Studio 功能：该桥接使用的是免费版自带的 Lua 脚本 API。Studio 21.1 用户已经可以使用 Blackmagic 原生 MCP 服务。

功能

• 15 个专用工具：项目概览、项目和时间线列表、媒体池片段、时间线项目、标记、切换时间线和项目、带状态轮询的渲染，以及对 Blackmagic 随附脚本参考文档的搜索。
• run_lua 满足其他需求：任何 Lua 5.1 代码块都能在 Resolve 内运行，并使用实时的 resolve 对象，返回 JSON、捕获的 print 输出和错误。
• 一个 .mcpb 包：将其安装到 Claude Desktop 后，服务会在首次启动时将两个 Lua 脚本复制到 Resolve 的用户脚本文件夹。
• 无需网络：服务和脚本通过请求文件与 Fusion 的偏好设置通信。不使用套接字或监听器，也不收集遥测数据。
• 响应迅速，交互流畅：在 Mac 上端到端测得每次调用约需 60 毫秒。

要求

• macOS（目前仅在 Apple Silicon 硬件上进行过测试）。
• Windows 10 或 11（实验性）。默认路径依据 Blackmagic 文档和论坛报告；目前尚未在 Windows 上进行测试。docs/windows.md 列出了需要检查的内容。
• DaVinci Resolve 21.1 免费版（已测试的版本为 21.1.0.17）。无需 Studio 版，也不针对 Studio 版。Blackmagic 没有说明此 Lua 宿主或其沙盒的相关信息，因此小版本更新可能会改变功能表现。
• Claude Desktop。它自带服务所需的 Node 运行时（Node 20 或更高版本）；无需安装其他内容。
• 使用这些工具时，Resolve 中必须打开一个项目。

安装

1. 下载 davinci-resolve-lua-mcp.mcpb（最新版本；发布说明和 SHA-256 值见 Releases 页面）。
2. 双击该文件，或将其拖到 Claude Desktop 窗口中。Claude Desktop 会显示扩展详情和五项设置；保留默认值并点击 安装。
3. 在 Resolve 中打开项目，然后点击 Workspace > Scripts > resolve_mcp_bridge。该脚本就是桥接程序；扩展首次启动时会将它放到这里。
   • 退出 Resolve 后，桥接程序会停止。每次启动 Resolve 后、使用工具前，都要再次点击该脚本。
4. 询问 Claude：“你已连接到 DaVinci Resolve 吗？”

在终端中运行以下任一命令，即可下载文件并打开相同的对话框。

macOS：

curl -fsSLo ~/Downloads/davinci-resolve-lua-mcp.mcpb https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest/download/davinci-resolve-lua-mcp.mcpb && open ~/Downloads/davinci-resolve-lua-mcp.mcpb

Windows（PowerShell）：

Invoke-WebRequest -Uri https://github.com/saadk408/davinci-resolve-lua-mcp/releases/latest/download/davinci-resolve-lua-mcp.mcpb -OutFile "$env:USERPROFILE\Downloads\davinci-resolve-lua-mcp.mcpb"; Start-Process "$env:USERPROFILE\Downloads\davinci-resolve-lua-mcp.mcpb"

如果没有打开任何内容，请在 Claude Desktop 中安装该文件：Settings > Extensions > Advanced settings > Install Extension。

若要更新，请下载新文件并打开；从文件安装的扩展不会自动更新。服务会在下次启动时刷新它的两个 Lua 脚本，因此之后请再次点击 Workspace > Scripts > resolve_mcp_bridge。若要自行构建安装包，请参阅开发。

启动和停止桥接程序

在 Resolve 中打开项目，然后点击 Workspace > Scripts > resolve_mcp_bridge。控制台中不会显示任何内容（免费版会屏蔽菜单脚本中的 print）；桥接程序会在后台循环运行，Resolve 仍可正常响应。在 Claude Desktop 中，resolve_status 随后会报告 alive: true，并显示产品、版本、版本类型、页面和已打开的项目。

重要

桥接程序会随 Resolve 启动和停止。每次启动 Resolve 后、使用工具前，都要再次点击 Workspace > Scripts > resolve_mcp_bridge。根据设计，它不会自动启动：通过 fusion:Execute 启动的循环会在整个会话期间占用 Fusion 的共享脚本执行器，因此 Scripts 菜单是唯一受支持的启动方式。

若要停止，请让 Claude 停止桥接程序（stop_bridge），或退出 Resolve。在桥接程序运行时再次点击脚本不会造成问题：新实例会接管，旧实例则会在收到发往新会话的第一个请求时退出。

示例提示词

Give me an overview of the open Resolve project.
List the clips in the root bin with their durations and frame rates.
What is on video track 1 of the current timeline?
Add a blue marker at frame 240 named "fix colour".
Delete all the red markers on this timeline.
Render the current timeline to ~/Movies/out as fix-v2 and tell me when it finishes.
Look up AppendToTimeline in the Resolve scripting docs.
Use run_lua to return the current timeline's start timecode and its item count on V1.

https://github.com/user-attachments/assets/febdf2b9-8e0d-4fbf-8462-0d6ecd98c829

工具

每个工具都会向客户端声明其访问权限提示。delete_markers 在未提供 confirm: true 时会拒绝执行，并会告知 Claude 先征求你的同意；run_lua 无需确认，并标记为具有破坏性，以便客户端发出警告。结果为 JSON，并附有相应的 structuredContent；支持分页的工具（list_media_pool_clips、get_timeline_items）会报告 total、offset、limit 和 truncated；每次失败都会说明下一步该怎么做，而不会抛出异常。

标记颜色：Blue、Cyan、Green、Yellow、Red、Pink、Purple、Fuchsia、Rose、Lavender、Sky、Mint、Lemon、Sand、Cocoa、Cream。

local project = resolve:GetProjectManager():GetCurrentProject()
local timeline = project:GetCurrentTimeline()
local items = timeline:GetItemListInTrack("video", 1)
local out = {}
for i = 1, #items do
  out[i] = { name = items[i]:GetName(), first = items[i]:GetStart(), last = items[i]:GetEnd() }
end
return { timeline = timeline:GetName(), start_timecode = timeline:GetStartTimecode(), items = out }

警告

此桥接一次只处理一个请求，且无法响应 Resolve 的模态对话框。长时间运行的同步 API 调用（RenderWithQuickExport、TranscribeAudio、Export、ArchiveProject，以及在实时保存关闭时对未保存项目调用 LoadProject）会阻塞桥接，直到调用完成。请使用 render_current_timeline 启动渲染，并轮询 get_render_status，不要在 run_lua 中等待。

设置

安装扩展后，Claude Desktop 会显示以下五项设置。标准 Resolve 安装请保留默认值。文件夹字段为空表示使用 路径 表中的平台默认值。

路径

Windows 路径仅有文档记录，未经实际测量；其中 Fusion 偏好设置文件夹的路径最不确定。通过 Microsoft Store 安装的 Claude Desktop 会将文件夹保存在 %LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\ 下。

故障排除

• Workspace > Scripts 中缺少桥接脚本。 请让 Claude 查询 resolve_status，并读取 bridge_script.outcome：
  • installed、updated 或 up_to_date：文件已位于脚本文件夹中。重新打开菜单；Resolve 会列出新文件，无需重启。
  • skipped_auto_install_off：此设置已关闭。请自行将 bridge/resolve_mcp_bridge.lua 和 scripts/claude_diag.lua 复制到该文件夹。
  • scripts_dir_missing：文件夹不存在。启动一次 Resolve 以创建该文件夹，或修正脚本文件夹设置；服务不会创建 Resolve 文件夹。
  • permission_denied 或 error：操作系统消息会说明原因。
• config_problems 指明了状态目录。 路径无法嵌入桥接脚本：其中包含 ]==]、双引号或换行符，以 @@ 开头，或在 macOS 上包含反斜杠（Windows 会将反斜杠改写为正斜杠）。在更改状态目录设置之前，自动安装会保持关闭。
• 我把脚本复制到了 Scripts/Deliver。 Resolve 也会将该文件夹中的脚本作为 Deliver 页面上可选择的渲染起始/结束脚本提供，但桥接脚本不应放在那里。删除该副本，仅将脚本保留在 Scripts/Utility 中。
• Fusion.prefs 未更新。 桥接脚本只会在响应请求时写入首选项，因此请先确认它正在运行（resolve_status）。首选项文件夹中最新的 Fusion.prefs 会被读取，无论配置文件叫什么；只有该文件夹位于其他位置时，才需要设置首选项文件夹。如果 Resolve 正在写入文件时保存失败，系统最多会重试五次；启动时保存失败则会每秒重试一次，直到成功。
• resolve_status 显示 prefs_missing。 Fusion 首选项文件夹中没有 Fusion.prefs。至少启动一次 Resolve，或将首选项文件夹设置为正确的文件夹。Windows 上的默认路径已有文档记录，但未经实测；如果你的 Fusion.prefs 位于其他位置，请按 docs/windows.md 中的说明报告路径。
• 请求卡住，或工具超时。 桥接脚本正忙于处理耗时较长的同步调用，或无法响应的模态对话框：请等待 Resolve 完成，然后重试。桥接脚本会拒绝超过 120 s 的请求，服务会在超时后移除 next.lua，因此无需手动清理。对于耗时较长的调用，可提高默认超时时间（最高为 300 s），或向 run_lua 传入 timeout_s。
• resolve_status 显示 lock_held。 另一个服务占用请求槽的时间超过了超时限制：可能是第二个 Claude Desktop 配置项、make smoke，或开发注册循环。请停止它，或更改状态目录设置。仅当 lock 文件中记录的 pid 不是服务进程时，才手动删除状态目录中的该文件。
• Windows 上的工具对 next.lua 返回 EBUSY 或 EPERM。 Windows 不允许删除或替换其他进程正打开的文件，而桥接脚本每隔 50 ms 就会重新读取请求文件，因此服务会重试约一秒。若错误持续出现，说明有其他程序一直占用该文件，通常是杀毒软件扫描器：请将状态目录排除在实时扫描之外。
• Windows 上的 resolve_status 显示 state_dir_ascii: false。 Resolve 的 Lua 可能无法打开包含非 ASCII 字符的路径，这会导致每个请求都超时。请将状态目录设置为仅包含 ASCII 字符的路径，例如 C:\rlb。
• Resolve 在会话中途重启。 resolve_status 显示 resolve_gone（记录的 pid 已终止）或 no_reply。会话记录会有意保留在重启后，而且没有心跳机制，因此不会有任何程序替你重启桥接脚本：请再次点击 Workspace > Scripts > resolve_mcp_bridge。
• 响应显示 truncated: true。 JSON 超出了上限（默认 64 KB）。对于 run_lua，result_preview 会包含其开头部分；超过上限时，专用工具会返回错误，说明上限并提示使用更小的 limit 或不同的 offset。请对列表工具使用 offset 和 limit，或减少 Lua 返回的内容。
• 重新安装时没有显示对话框。 请在 Settings > Extensions 下移除扩展，然后再次打开 .mcpb；Claude Desktop 会立即重新启动服务。
• 工具返回 bad_response。 已安装的脚本与服务使用的协议不一致，通常是其中一个升级后导致的。请重启 Claude Desktop，让服务重新安装脚本，然后从 Scripts 菜单重新启动该脚本。
• 日志位置。 服务自身的日志是状态目录中的 server.log（达到 5 MB 时会截断；路径也可在 resolve_status 中查看）。Claude Desktop 会将服务的 stderr 保存为日志文件夹中的 mcp-server-DaVinci Resolve Lua MCP.log；该文件记录连接情况，不记录聊天中的工具调用。已安装的扩展位于扩展文件夹中的 local.mcpb.saad-khan.davinci-resolve-lua-mcp（两者的位置见 Paths）。

PREFS=~/Library/Application\ Support/Blackmagic\ Design/DaVinci\ Resolve/Fusion/Profiles/Default/Fusion.prefs
grep -o 'RLBResp = "[^"]*"' "$PREFS" | cut -d: -f2 | tr -d '"' | xxd -r -p

$prefs = Join-Path $env:APPDATA 'Blackmagic Design\DaVinci Resolve\Support\Fusion\Profiles\Default\Fusion.prefs'
$hex = ([regex]::Match((Get-Content -Raw -LiteralPath $prefs), 'RLBResp = "([^"]*)"').Groups[1].Value -split ':')[1]
$bytes = [byte[]]::new($hex.Length / 2); for ($i = 0; $i -lt $bytes.Length; $i++) { $bytes[$i] = [Convert]::ToByte($hex.Substring(2 * $i, 2), 16) }
[Text.Encoding]::UTF8.GetString($bytes)

安全

警告

任何能在这台机器上写入一个文件的程序，都能以你的权限在 Resolve 中运行 Lua。批准 run_lua 代码块前，请先阅读。

• 状态目录就是安全边界。macOS 会以 0700 模式创建该目录；Windows 则沿用你的个人资料文件夹权限（服务本身不设置权限）。
• 下一个回答覆盖之前，最后一个回答会以十六进制编码的形式保留在 Fusion.prefs 中。在实测的 Mac 上，该文件的模式为 0666，因此任何本地账户都能读取上一个回答；在 Windows 上，该文件默认位于 %APPDATA% 下，只有你的账户可以访问（未经实测）。正常停止时，会将会话记录标记为 stopped，并用停止确认信息替换最后一个回答。
• 此扩展以你的用户权限运行在 Claude Desktop 的进程模型内，本身没有沙盒。它只会写入自己的状态目录，以及 Resolve 用户脚本文件夹中的两个 Lua 文件。
• 不联网：服务不会打开套接字或发送请求。文件输入，偏好设置输出。

隐私政策

此扩展完全在你的机器上运行，不会向任何地方发送数据。完整政策见 PRIVACY.md；简而言之：

• 收集。 它会处理 Claude 发送的内容（Lua 代码、标记文本、名称、路径）以及 Resolve 返回的内容（项目、时间线、片段和标记元数据、媒体路径）。不收集账户、凭据、遥测、分析数据或崩溃报告。
• 使用和存储。 这些数据仅存储在请求文件中（每次调用一次，随后删除）、Fusion.prefs 中的最后一个回答、服务日志中（ID、耗时、路径和错误消息；绝不记录 Lua 代码、参数或结果），以及 Claude Desktop 保存的该日志副本中。
• 与第三方共享。 此扩展不会共享数据。Claude Desktop 会根据 Anthropic 的隐私政策，将工具输入和结果作为对话的一部分发送给 Anthropic；下载文件由 GitHub 提供。
• 保留期限。 回答会保留至下次调用或桥接程序启动时被覆盖；日志会保留至超过 5 MB；除此之外，文件会一直保留，直到你按照卸载中的说明删除。
• 联系。 有疑问：提交 issue。安全问题：请参阅仓库的 Security 选项卡，具体说明见 SECURITY.md。

卸载

1. 在 Claude Desktop 的 Settings > Extensions 中移除 “DaVinci Resolve Lua MCP”。
2. 从脚本文件夹中删除 resolve_mcp_bridge.lua 和 claude_diag.lua（参见路径）；在 Mac 上的代码检出目录中运行 make uninstall-bridge，即可准确移除这两个文件。
3. 删除状态目录。

Global.ResolveLuaBridge.* 键会留在 Fusion.prefs 中（正常停止后不到 2 KB：会话记录、停止确认信息和八个已清空的键）。如果你希望文件保持原样，可以从 Fusion 的偏好设置中移除这些键。

开发

先决条件：

• Node 20 或更高版本以及 npm（Makefile 会加载 ~/.nvm/nvm.sh）。
• DaVinci Resolve 安装：Lua 测试会通过其捆绑的 fuscript 运行，路径为 /Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fuscript。
• 可选：lua-language-server，用于 make lint-lua。
• Makefile 仅支持 macOS。在 Windows 上，请通过 Git Bash 运行相同的检查，具体步骤见 docs/windows.md；fuscript 测试和 make smoke 在 Windows 上没有对应方案。

git clone https://github.com/saadk408/davinci-resolve-lua-mcp.git
cd davinci-resolve-lua-mcp
npm install
make test      # Lua checks under fuscript + the Node suite
make bundle    # dist/davinci-resolve-lua-mcp.mcpb, validated and probed
make install   # make bundle, then open the .mcpb so Claude Desktop shows its dialog

开发流程：只需运行一次 make dev-register，之后每次更改都运行 make build 并重启 Claude Desktop，无需重新打包。开发条目和已安装扩展可以同时运行：请求槽锁按请求获取并立即释放，因此空闲服务不会阻塞另一个服务。两者响应的工具名称相同，所以测试其中一个时，请在 Claude Desktop 中禁用另一个。CONTRIBUTING.md 介绍了分支和发布流程。

发布：推送 vX.Y.Z 标签会运行 .github/workflows/release.yml，该工作流会在带标签的提交上运行 Node 检查和 make bundle，为打包文件构建来源信息生成证明，然后发布不可变的 GitHub Release，并附上打包文件及其 SHA-256 值；带注释标签的消息会作为发布说明的引言。第二个任务会将发布内容作为 io.github.saadk408/davinci-resolve-lua-mcp 发布到 MCP Registry，并附上发布文件的哈希值。使用 gh attestation verify davinci-resolve-lua-mcp.mcpb -R saadk408/davinci-resolve-lua-mcp 验证下载的打包文件。测试工作流还会在 Windows 运行器上运行 Node 检查和打包检查。

说明

make smoke 会创建并删除名为 bridge-smoke 的时间线，在其上添加并删除标记，并设置项目的渲染目标目录和文件名。SMOKE_PROJECT 必须是 Resolve 中当前打开的项目名称，而且应该是一个临时项目，绝不能是真正的剪辑项目。名称不一致时，运行会拒绝继续。

目录结构：

• bridge/resolve_mcp_bridge.lua：在 Resolve 中运行的循环逻辑，是一个无依赖、少于 600 行的文件。
• src/：TypeScript 服务端。server.ts 包含 15 个工具，lua.ts 包含所有 Lua 代码片段和唯一的字符串转义辅助函数，protocol.ts 包含请求槽和锁，prefs.ts 是 Fusion.prefs 读取器，bridgeInstall.ts 实现自动安装。
• scripts/claude_diag.lua：沙盒诊断脚本，也随软件包一并提供。
• tests/：Node 测试套件；tests/lua/：fuscript 检查。
• docs/：Windows 测量清单（windows.md）和 README 的截图（images/）。

致谢

本项目基于以下项目的成果构建：

• AutoSubs - 在免费版 21.1 中通过 Fusion 首选项实现的 Lua 桥接，本项目采用了该通道
• samuelgursky/davinci-resolve-mcp - 通过 Python 脚本 API 服务于 DaVinci Resolve Studio 的 MCP 服务

DaVinci Resolve 是 Blackmagic Design Pty Ltd 的商标。本项目与 Blackmagic Design 无关，也未获得其认可。