DaVinci Resolve Lite MCP

davinci-resolve-lite-mcp

DaVinci Resolve Lite 21.1+（App Store 版）不可用——Python 菜单脚本已被阻止；MCP 服务无法启动。适用于 21.1 之前的 Lite 版或 Studio 版。

https://github.com/user-attachments/assets/8429932f-643b-4131-bdf6-dad0d3399137

Claude 在 DaVinci Resolve Lite 中创建开场标题——通过 insert_fusion_title + style_fusion_title，根据自然语言请求生成带有辉光和缩放入场关键帧效果的金色「GameHelper」Text+ 节点。

一个 MCP 服务，让 Claude Code 等 AI 客户端能够控制 DaVinci Resolve——包括仍允许 Python 菜单脚本的免费（Lite）版本，而现有的 davinci-resolve-mcp 项目无法驱动这些版本。

免费版会阻止外部脚本，但仍可运行从其自身的 Workspace > Scripts 菜单启动的 Python 脚本。本项目利用了这条路径：MCP 服务以菜单脚本的形式在 Resolve 内部运行，并通过一个本地 HTTP 端点公开 Resolve 的 Python API，供 Claude 连接。

Claude Code ──HTTP JSON-RPC (MCP)──▶  127.0.0.1:8765/mcp
                                          │   server runs INSIDE Resolve
                                          │   (Workspace > Scripts > Utility)
                                          ▼
                              command queue → main script thread
                                          ▼
                              global `resolve` object → Resolve API

工具

用自然语言向 Claude 提出请求；它会通过这些工具操作 Resolve——请参见上方演示。完整的 163 个工具列表请参阅工具参考，涵盖剪辑、调色、渲染、媒体池和 Fusion 标题样式设置。

为什么这适用于兼容的免费版本

• 兼容的免费版 Resolve 允许从脚本菜单运行 Python 脚本（仅限制外部网络脚本）。
• 菜单脚本可直接获取 resolve 对象，并可运行足够长时间的循环——足以托管服务。
• 沙盒化的 Lite 应用自带 com.apple.security.network.server 权限，因此可以打开 localhost 监听套接字。
• 零依赖——仅使用纯 Python 标准库。无需向 Resolve 的解释器中执行 pip install。

要求

• macOS，且安装了 DaVinci Resolve Studio，或仍在 Workspace > Scripts 中提供 Python 脚本的 DaVinci Resolve Lite／免费版。
• Claude Code（或任何支持 Streamable HTTP 传输的 MCP 客户端）。

警告

DaVinci Resolve Lite 21.1+ 兼容性问题： Blackmagic 的 DaVinci Resolve 21.1 release notes 和当前用户反馈表明，免费版／App Store Lite 版可能会屏蔽 Python 菜单脚本。发生这种情况时，Workspace > Scripts 可以打开，但其中的类别文件夹（Utility、Comp、Edit、Color、Deliver）都是空的，即使 MCP 文件已正确安装在 Fusion/Scripts/Utility 文件夹中也是如此。

此服务必须作为 Python 菜单脚本从 Resolve 启动。如果你的 Lite 版本屏蔽了 Python 脚本，重新安装此项目也无法解决菜单为空的问题。请使用仍允许 Python 菜单脚本的 21.1 之前的 Lite 版本，或使用 Studio／未屏蔽的版本。Lua Console 可能仍然可以打开，但这还不够：如果 bmd.scriptapp("Resolve") 返回 nil，则 Resolve 脚本对象在其中也不可用。

安装

git clone https://github.com/2sem/davinci-resolve-lite-mcp.git
cd davinci-resolve-lite-mcp
./install.sh

如果不想克隆仓库，也可以通过 pip 安装：

pip install davinci-resolve-lite-mcp
davinci-mcp-install

davinci-mcp-install 执行的操作与 install.sh 完全相同（Lite／Studio 检测方式相同，复制与符号链接逻辑相同），只是从通过 pip 安装的软件包而非 git 检出目录中读取文件。davinci-mcp-uninstall 则会撤销安装。无论采用哪种方式，以下沙盒说明仍然适用，而且你仍需从 Resolve 自带的菜单启动服务——请参阅运行。

macOS 用户安装说明。 如果你看到 Defaulting to user installation because normal site-packages is not writeable，说明 pip 将控制台脚本安装到了 $(python3 -m site --user-base)/bin，该目录通常不在 PATH 中。你可以运行完整路径—— "$(python3 -m site --user-base)/bin/davinci-mcp-install"——或将该 bin 目录添加到 PATH。两个命令之间请使用 &&，不要使用 &：单独使用 & 会在后台运行 pip install，导致 davinci-mcp-install 在软件包安装完成前就开始运行。

此项目也列于 MCP Registry，名称为 io.github.2sem/davinci-resolve-lite-mcp （验证）——仅供发现。该条目仅包含元数据（没有自动安装用的 packages／remotes 条目）：此服务无法像典型的注册表服务那样由 MCP 客户端启动，因为它必须在 Resolve 自带的嵌入式 Python 解释器中运行，并由用户从 Scripts 菜单手动启动。请通过上述两种方式之一进行安装。

install.sh 会部署：

• 两个启动脚本到 Fusion/Scripts/Utility（Resolve 会扫描此文件夹以显示 Scripts 菜单；Utility 会在每个页面上显示），以及
• resolve_mcp 软件包到 Fusion/Scripts/MCP——Resolve 不会扫描此文件夹，因此辅助模块不会显示在菜单中。

Lite 容器路径会自动检测。

沙盒说明（重要）。 DaVinci Resolve Lite 受沙盒限制，只能读取自身容器、~/Movies 以及你通过交互方式选择的文件。沙盒应用无法访问指向这些位置之外的符号链接（例如指向 ~/Projects 下克隆目录的链接），因此菜单脚本会静默地无法运行。为此，Lite 版上的 install.sh 会将文件复制到容器中（而未受沙盒限制的 Studio 版则只创建符号链接）。拉取更新后，请重新运行 ./install.sh。

Resolve 只会枚举 Scripts 菜单的类别文件夹（Utility / Comp / Tool / Edit / Color / Deliver）——因此启动脚本放在 Utility 中，而软件包则隐藏在 MCP 中。

同样的沙盒限制也适用于你要求工具使用的文件路径： 导出／导入目标应设为 ~/Movies（或其他已授权的位置），否则 Resolve 无法写入／读取这些文件。

运行

1. 在 DaVinci Resolve 中：Workspace > Scripts > Utility > davinci_mcp_server。

   

2. 打开 Workspace > Console — 此处会显示端点和端口：

   MCP endpoint:  http://127.0.0.1:8765/mcp
   Add to Claude Code:
     claude mcp add --transport http davinci http://127.0.0.1:8765/mcp
   

   启动指南会显示在 Resolve Console（Workspace > Console）中。 由于服务会持续运行，其 Console 输出可能会缓冲，直到服务停止， 因此两个脚本也会将每一行内容同步写入日志文件：

   ~/Movies/davinci-resolve-lite-mcp.log
   

   使用 ./logs.sh 实时查看。（使用 DAVINCI_MCP_LOG_DIR 更改目录。）使用 ~/Movies 是因为沙盒化的 Lite 应用 可以在该目录中写入文件。

   启动后，每次工具调用都会在 Console 中记录为单行 （[davinci-mcp] <name> <args> -> ok|error (Nms)）：

   

   更新检查。 与 brew/CocoaPods 类似，每次启动时都会在后台检查 PyPI 是否有 更新版本；如果有，会在 Console 中显示一行提示 — 不会阻塞启动，任何故障（离线、PyPI 宕机）都不会显示提示，仅记录在日志文件中。使用 DAVINCI_MCP_SKIP_UPDATE_CHECK=1 禁用。

3. 将其注册到 Claude Code（仅需一次）：

   claude mcp add --transport http davinci http://127.0.0.1:8765/mcp
   

   然后在 Claude Code 中使用 /mcp 命令验证 / 重新连接 — 此命令会列出已连接的服务并重新连接它们。如果启动脚本时 Claude 已在运行，请输入 /mcp（或重启会话），以便连接 davinci 服务。

4. 让 Claude 控制 Resolve。

故障排除：Workspace > Scripts 为空

如果 Workspace > Scripts 显示了预期的类别文件夹，但所有文件夹都是空的，说明 Resolve 未加载菜单脚本。重新安装前请先检查：

flowchart TD
  A[Install MCP scripts] --> B[Open Resolve]
  B --> C{Workspace > Scripts has entries?}
  C -->|Yes| D[Run Utility > davinci_mcp_server]
  C -->|No, all categories empty| E[Resolve is not loading Python menu scripts]
  E --> F{Lite 21.1+ / App Store build?}
  F -->|Yes| G[Use pre-21.1 Lite or Studio/non-blocked build]
  F -->|No| H[Enable scripting in Preferences and restart Resolve]

• 在 DaVinci Resolve Studio / 带脚本偏好设置的版本中，将 Preferences > System > General > External scripting using 设置为 Local 或 Network，保存，然后完全重启 Resolve。

• 在 DaVinci Resolve Lite 21.1+ / 禁用了 Python 的 App Store 版本 （参见 Blackmagic 的 21.1 发行说明）中， 该偏好设置可能不可用，Scripts 菜单也会保持为空。由于此 MCP 服务需要在 Resolve 内执行 Python 菜单脚本，因此无法在这些版本上启动。

• 如果 Workspace > Console 仍显示 Lua> 提示符，这只能证明 Lua 控制台存在。你可以通过以下命令检查 Resolve 脚本对象是否可用：

  print("lua ok")
  resolve = bmd.scriptapp("Resolve")
  print(resolve)
  

  如果第二行输出 nil，说明当前 Lite 版本也未通过 Lua 暴露 Resolve 脚本对象。

• 隐藏的 Fusion/Scripts/MCP 文件夹不应显示在菜单中；在兼容版本的 Utility 下，只应显示 davinci_mcp_server 和 stop_davinci_mcp_server。

配置端口（稳定，推荐）

默认情况下，服务在 8765 上监听，如果该端口被占用，就会自动递增到 8766、8767，……（其他本地工具可能已经占用了 8765）。由于每次启动时端口竞争的胜出者可能不同，你向 Claude 注册的 URL 可能会发生变化，从而出现以下情况：

Failed to reconnect to davinci: HTTP 404 at http://127.0.0.1:8765/mcp

若要永久固定端口，请创建一个小型 JSON 配置文件。通过这种方式设置端口后，它就是固定的——服务会绑定到指定端口，绝不会自动递增，因此只需向 Claude 注册一次，URL 就不会变化。

创建 ~/Movies/davinci-resolve-lite-mcp.config.json：

{ "host": "127.0.0.1", "port": 8770 }

为什么是 ~/Movies 而不是 ~/.config？ Lite 应用受沙盒限制，只能读取自己的容器、~/Movies 以及你通过交互方式选择的文件——~/.config 位于沙盒之外，因此 Lite 无法读取它（这也是日志文件位于 ~/Movies 的原因）。对于非沙盒化的 Studio版本，服务也会检查 ~/.config/davinci-resolve-lite-mcp/config.json，因为该路径是常见配置路径。

然后重启服务（Scripts > Utility > stop_davinci_mcp_server，然后运行 davinci_mcp_server），并使用固定端口向 Claude 注册一次：

claude mcp add --transport http davinci http://127.0.0.1:8770/mcp

控制台横幅会确认配置来源——查找 Port : pinned (from …) — will not auto-increment。

解析顺序（优先级从高到低）：DAVINCI_MCP_PORT / DAVINCI_MCP_HOST 环境变量，然后是配置文件，最后是内置默认值。环境变量也会固定端口，但通过 Dock 启动的 Resolve 无法读取 shell 中的 export；配置文件是最简单的持久化选项。DAVINCI_MCP_CONFIG=/path/to.json 会仅使用指定的配置文件——如果该路径不存在或文件格式错误，服务会回退到内置默认值，而不会读取 ~/Movies / XDG。

如果端口已经发生变化，而 Claude 指向了错误的端口，请重新指向正确的端口：

claude mcp remove davinci
claude mcp add --transport http davinci http://127.0.0.1:<actual-port>/mcp

停止

以下任一方式都可以停止服务：

• 从菜单停止： Workspace > Scripts > Utility > stop_davinci_mcp_server
• 从终端停止： ./stop.sh
• 退出 DaVinci Resolve

菜单停止脚本和 stop.sh 都会向服务的 /shutdown 端点发送 POST 请求，并扫描服务启动时使用的同一端口范围。

只有在端口未固定时，才会从 8765 开始自动递增。若要固定端口，让 URL 在每次启动时都保持不变，请参阅 配置端口。

工具

163 个工具，涵盖完整工作流程：

• 状态与导航 — 页面切换、项目/时间线设置
• 项目与时间线 — 加载/创建/复制、标记、场景剪切、生命周期
• 轨道 — 添加/删除、启用/锁定/重命名
• 剪辑 — 放置/追加/删除片段、标题与生成器、变换/裁剪/缩放
• 媒体池与存储 — 导入/删除、属性与元数据、标记、浏览磁盘
• 调色 — 节点图 LUT/启用、重置调色、静帧
• 渲染与导出 — 渲染队列、格式/编解码器、帧/时间线/项目导出与导入

完整的工具参考请参阅 docs/TOOLS.md。

每次工具调用都会以单行形式记录到 Resolve 控制台和日志文件中：[davinci-mcp] <name> <args> -> ok|error|EXCEPTION (Nms)。

项目布局

src/davinci_mcp_server.py        thin launcher (deployed to Scripts/Utility)
src/stop_davinci_mcp_server.py   stop launcher
src/resolve_mcp/                 the server package (deployed to Scripts/MCP, hidden)
    config · logio · connection · bridge · tools · server
tests/test_server.py             offline tests (fake Resolve, no app needed)
install.sh · uninstall.sh · stop.sh · logs.sh
docs/TOOLS.md                    full per-tool reference
fallbacks/                       documented gotchas + fixes

测试

• 离线（无需 Resolve 和服务）— 导入、分发器和工具数量冒烟测试：

  python3 tests/test_server.py
  

• 实时集成 — 针对每个工具运行中的服务进行一次测试（Resolve 已打开，并有一个项目和媒体片段，且已启动 davinci_mcp_server）：

  python3 tests/live_test.py                 # all features
  python3 tests/live_test.py set_timecode    # run the test(s) for given feature(s)
  

  每个测试的名称都与工具名称相同，因此更改工具时，可以只运行对应的测试：python3 tests/live_test.py <tool>。测试可逆（使用临时时间线和临时文件，并会清理）。依赖文件和会破坏会话的工具会通过错误路径进行检查；仅限 Studio 或开销较大的工具（例如 detect_scene_cuts、render_current_timeline、quick_export）会注明原因并跳过。少数标记和静帧测试依赖干净的 Resolve 会话状态——如果测试不稳定，请在重新启动后重试。

贡献

有关如何添加工具、运行测试套件、仅使用标准库并优先支持 Lite 的限制，以及发布流程，请参阅 CONTRIBUTING.md。

范围

此服务面向免费版（Lite），有意仅涵盖可在该版本中运行的 API。仅限 Studio 或付费版的功能特意不予支持（在 Lite 中无操作或报错），具体包括：音频转录、从音频生成字幕、Magic Mask、稳定、智能重构、Dolby Vision 分析、语音隔离，以及云项目／数据库管理。其余尚未封装的方法都是简单的访问器（GetUniqueId、缓存模式、Fusion 合成内部项、takes、立体声／3D、布局和烧录预设、遮罩）——并非功能缺失。

已知限制

• 可通过名称（在当前媒体池文件夹内）或通过 id（id／ids，可在任意媒体箱中解析）指定片段——如果名称有歧义或片段位于其他文件夹，请传入 id／ids。
• 工具参数会根据每个工具的 JSON Schema 进行验证（必填字段、基本类型和枚举值）；格式错误的调用会返回明确错误，并指出出错的参数。不会穷尽检查深层／嵌套的 Schema 约束。

安全提示

服务仅绑定到 127.0.0.1，因此只能从你的设备访问。任何能够连接该端口的本地进程都可以通过此服务控制 DaVinci Resolve——请仅在可信设备上运行。

服务自行发起的唯一出站请求是启动时的更新检查（向 PyPI 的公共 JSON API 发送 GET 请求，以查询当前版本号——不会发送其他数据）。如果不希望它发出任何请求，请设置 DAVINCI_MCP_SKIP_UPDATE_CHECK=1 将其禁用。

许可证

MIT — 参阅 LICENSE。