DaVinci Resolve MCP (free edition)

davinci-resolve-mcp

让 Claude Code 驱动免费版 DaVinci Resolve 21.1。

Resolve 21.1 免费版已从 Workspace > Scripts 菜单中移除 Python 脚本，并阻止外部脚本运行。Lua 菜单脚本仍可运行。本项目利用了这一点：一个 Lua 桥接程序在 Resolve 内运行，一个精简的 Python MCP 服务在外部运行。服务将 Lua 发送给桥接程序，桥接程序针对实时的 resolve 对象运行代码，并将结果发回。实测每次调用耗时约 80 至 95 ms。项目提供 33 个工具，另有 run_lua，可用于执行命名工具未涵盖的操作。

要求

• macOS
• DaVinci Resolve 21.1.2，免费版或 Studio 版
• Claude Code
• /usr/bin/python3 中的 Python 3.9 或更高版本
• 无需通过 pip 安装。服务仅使用标准库。

安装

git clone https://github.com/kingjamesch/davinci-resolve-mcp.git
cd davinci-resolve-mcp
./install.sh

安装程序会执行以下四项操作：

1. 将两个 Lua 脚本复制到 ~/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Scripts/Utility/。并将状态目录路径写入桥接程序。
2. 创建状态目录 ~/Library/Application Support/Blackmagic Design/DaVinci Resolve/ClaudeMCP，权限设为 0700。
3. 在用户级别向 Claude Code 注册此服务，名称为 davinci。
4. 打印后续步骤。

安装程序打印的后续步骤：

NEXT STEPS
1) Quit and reopen DaVinci Resolve once (it scans the Scripts menu only at startup).
2) In Resolve: Workspace > Scripts > Claude_MCP_Bridge (do this once per Resolve session; Claude_MCP_Bridge_Stop stops it).
3) In Claude Code run /mcp and check that 'davinci' is connected, then ask for resolve_status.

首次安装后需要重启一次 Resolve。Resolve 只会在启动时读取 Scripts 文件夹。

其他标志：

标志	效果
--claude-desktop	也将 davinci 添加到 Claude Desktop 配置中。可选。现有配置会先备份。
--no-claude	跳过 Claude Code 注册。
--check	检查已安装的内容。
--uninstall	移除 Lua 脚本和 Claude Code 注册。添加 --purge 还会删除状态目录。./uninstall.sh 执行相同操作。

安装为 Claude Code 插件

如果只使用 Claude Code，可以跳过克隆操作。在 Claude Code 中：

/plugin marketplace add kingjamesch/davinci-resolve-mcp
/plugin install davinci-resolve@davinci-resolve-mcp
/davinci-resolve:setup

此插件会自行注册 davinci 服务；/davinci-resolve:setup 会将两个 Lua 脚本复制到 Resolve 的 Scripts 文件夹中。然后重启一次 Resolve，并点击 Workspace > Scripts > Claude_MCP_Bridge。插件还附带一个 resolve 技能，其中包含 Claude 所需的约定 （绝对帧、标记规则、Lua 惯用写法、仅适用于 Studio 版的注意事项）。

请使用插件或 ./install.sh，不要同时使用两者，否则 Claude Code 会看到两个 davinci 服务 （claude mcp remove davinci -s user 可移除基于克隆的服务）。

此服务也列在 MCP Registry 中，名称为 io.github.kingjamesch/davinci-resolve-mcp，供用户发现。该列表仅包含元数据：请按上述说明通过插件或克隆方式安装，因为桥接程序必须手动放入 Resolve 中。

日常使用

1. 打开一个包含项目的 Resolve。
2. 点击 Workspace > Scripts > Claude_MCP_Bridge。每次 Resolve 会话只需执行一次。
3. 在 Claude Code 中，先请求 resolve_status。它会告知桥接程序是否正常运行。
4. 如需停止桥接程序，点击 Workspace > Scripts > Claude_MCP_Bridge_Stop。

提示词示例：

• “调用 resolve_status，然后列出我的时间线。”
• “在当前时间线的 00:00:10:00 处添加一个名为 ‘fix audio’ 的红色标记。”
• “导入 /Users/me/Footage/day1 中的所有内容，并据此创建一个名为 Day 1 的时间线。”
• “将当前时间线的 mp4 渲染任务加入队列，输出到 /Users/me/Exports，开始渲染，并在完成后告诉我。”
• “使用 run_lua 列出视频轨道 1 上的片段颜色。”

工具

完整参考文档（包含所有参数）见 docs/TOOLS.md。该文档由代码生成。

• 状态和项目： resolve_status、list_projects、get_project_info、get_project_setting、open_project、save_project、set_project_setting、open_page
• 时间线： list_timelines、get_timeline_info、get_timeline_items、get_timeline_markers、set_current_timeline、set_timecode、create_timeline、add_marker、delete_markers、insert_timeline_element、delete_timeline_items、export_timeline
• 媒体池： list_media_pool、get_clip_properties、create_media_pool_folder、import_media、append_clips_to_timeline
• 渲染： get_render_status、list_render_options、add_render_job、start_render、stop_render、delete_render_job
• 备用方案： run_lua 可在 Resolve 内运行任意 Lua 5.1 代码块。scripting_api_docs 可搜索 Blackmagic 随附的 API 参考文档，让 Claude 正确编写 Lua。

约定：路径均为绝对路径；帧数是时间线自身编号中的整数；时间码格式为 HH:MM:SS:FF；轨道和项目索引从 1 开始。

工作原理

• Claude Code 通过标准输入输出启动 server.py。该服务使用 MCP 通信，不持有网络套接字。
• 发送请求时，服务会在状态目录下创建文件夹。请求会以十六进制编码后写入文件夹名称。
• Lua 桥接程序每 30 毫秒列出这些文件夹，解码请求并使用绑定的 resolve 对象执行请求。
• 桥接程序通过 fu:SetData 返回结果，Resolve 会将其写入 Fusion.prefs。服务会轮询该文件。
• 最后一次响应会保留在 Fusion.prefs 中，并在写入约 10 秒后清除；桥接程序停止时也会清除该响应。
• 多个 Claude Code 会话可以共用一个 Resolve：每个服务都会在状态目录中获取锁，因此请求会逐个运行。

通信格式见 docs/PROTOCOL.md。设计记录见 docs/MCP-RECORD.md。

故障排除

• 工具提示桥接程序未运行。 打开一个项目，然后点击 Workspace > Scripts > Claude_MCP_Bridge，再重试。
• Workspace > Scripts 中没有 Claude_MCP_Bridge。 安装后没有重启 Resolve。退出并重新打开 Resolve。运行 ./install.sh --check 确认文件已就位。
• 工具超时。 Resolve 可能正在显示对话框，例如 Studio 升级提示，或导入后出现的帧率问题。请在 Resolve 中关闭对话框。长时间运行的操作也会阻塞桥接程序，直到操作完成。
• 仅限 Studio 的功能失败。 请勿在免费版中使用仅限 Studio 的功能。此类功能会失败，或打开升级对话框并阻塞桥接程序。
• 旧版 davinci-resolve-lite-mcp Python 脚本没有任何作用。 它们无法在 21.1 或更高版本中运行，因为 Python 脚本不再显示在 Scripts 菜单中，且外部脚本功能已被屏蔽。

暂未包含

调色页面节点工具、图库和静帧、Fairlight、复合片段和 Fusion 片段、键盘和预设导入或导出、项目归档和还原、Resolve 启动时自动启动桥接程序、Claude Desktop .mcpb 包，以及 Windows。run_lua 目前可以实现其中大部分功能。要从工具列表中移除 run_lua，请在服务环境中设置 DAVINCI_MCP_DISABLE_RUN_LUA=1。

安全态势

• 仅限本地。服务不会开放网络端口，也不会发送遥测数据。
• 无需凭据。身份由你的 macOS 用户决定。
• 任何可以写入状态目录的人都能以你的身份在 Resolve 中运行 Lua。该目录以 0700 模式创建。
• 破坏性工具需要 confirm: true。run_lua 用途开放，因此 Claude 会被告知，在运行会删除或覆盖内容的代码前先征求你的同意。
• 响应大小设有上限。超出上限的结果会标记为 truncated。
• Fusion.prefs 对你的用户可读，并会保留上一次响应，直到将其清除。
• 要关闭服务，请运行 Stop 脚本并删除状态目录。
• 服务仅将工具名称、状态和耗时记录到 stderr。绝不会记录参数或结果。

开发

运行测试：

/usr/bin/python3 -m unittest discover -s tests

更改任何工具后，重新生成工具参考文档：

/usr/bin/python3 scripts/gen_tools_doc.py

如果 docs/TOOLS.md 未更新，或工具被重命名，测试就会失败。

目录结构：

server.py                  stdio entry point
install.py, install.sh     installer, uninstaller (uninstall.sh)
bridge/                    Lua scripts that run inside Resolve
davinci_mcp/               server, transport, prefs parser, Lua encoder, docs index
davinci_mcp/tools/         one module per tool group
docs/                      MCP-RECORD.md, PROTOCOL.md, TOOLS.md (generated)
scripts/gen_tools_doc.py   generates docs/TOOLS.md
tests/                     unit tests and the offline bridge round trip

致谢

• JSON 编码器和若干经测量得出的宿主事实改编自 saadk408/davinci-resolve-lua-mcp，采用 MIT 许可证。
• 将 Lua 通过偏好设置文件用作通道的想法来自 AutoSubs。

许可证

MIT。请参阅 LICENSE。