davinci-resolve-lite-mcp

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

Claude 通过一句自然语言请求，在 DaVinci Resolve Lite 中构建一个开场标题——一个带发光和缩放关键帧动画的金色 "GameHelper" Text+ 节点，并借助 insert_fusion_title + style_fusion_title 完成。

一个 MCP 服务器，让 Claude Code 这样的 AI 客户端能够控制 DaVinci Resolve——包括现有 davinci-resolve-mcp 项目无法驱动的免费（Lite）版。

免费版会拦截外部脚本，但它仍然可以通过自身的 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 标题样式——详见工具参考。

Related MCP server: resolve-mcp

为什么免费版也能用

• 免费版 Resolve 允许运行脚本菜单中打开的脚本（仅外部网络脚本受限制）。

• 菜单脚本可以免费获得 resolve 对象，并且可以运行长时间循环——足够承载一个服务。

• 沙盒化的 Lite 应用自带了 com.apple.security.network.server 许可证，因此可以打开 localhost 监听端口。

• 零依赖——纯 Python 标准库。无需向 Resolve 的解释器 pip install 包。

系统要求

• 装有 DaVinci Resolve（免费版/Lite 或 Studio）的 macOS。

• Claude Code（或任何支持 Streamable HTTP 传输的 MCP 客户端）。

安装

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

如果您不想 clone 该仓库，也可以使用 pip 安装：

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

davinci-mcp-install 的安装方式与 install.sh 完全相同（相同的 Lite/Studio 检测、相同的 copy 与 symlink 逻辑）——只是它从你 pip 安装的包中读取文件，而不是从 git checkout。davinci-mcp-uninstall 用于撤销。无论如何，下面的 mac 沙盒注意依然适用，并且你仍然需要从 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 客户端以典型 Registry 服务器的方式拉起，因为它必须运行在 Resolve 自带的 Python 解释器中，并从脚本菜单手动启动。请按上面两种方式之一安装。

install.sh 会部署：

• 将两个启动程序放在 Fusion/Scripts/Utility 中（Resolve 会把该文件夹作为脚本菜单扫描；Utility 在每页都显示）；——

• 而这个 resolve_mcp 包放在 Fusion/Scripts/MCP——该文件夹 Resolve 不扫描，辅助不会且模块会出现在菜单中。

Lite 容器路径会被自动检测出来。

沙箱注意（重要）。 DaVinci Resolve Lite 是沙箱化的，只能读取自己的容器、~/Movies 以及你手动选择的文件。指向这些位置之外的符号链接（例如 ~/Projects 下的一个克隆）沙箱应用无法跟随，所以菜单脚本会静默运行失败。为此 install.sh 在 Lite 上会复制文件到容器内（只在非沙箱的 Studio 版本上创建符号链接）。拉取更新后请重新运行 ./install.sh。

Resolve 只枚举脚本菜单中的分类文件夹（Utility / Comp / Tool / Edit / Color / Deliver），因此启动程序放在 Utility 中、而把包隐藏到 MCP。

沙箱限制也适用于您要求工具使用的文件路径：导出/导入应该指向 ~/Movies（或其他被允许的目录），否则 Resolve 无法写入/读取它们。

运行

1. 在 DaVinci Resolve 中：工作区 > 脚本 > 工具 > 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。

配置端口（稳定，推荐）

默认情况下，服务器监听 8765，如果该端口被占用， 则自动递增到 8766、8767...（另一个本地工具可能已经占用）。因为这种竞争的结果每次启动都可能不同，所以你在 Claude 中注册的 URL 可能漂移，表现为：

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

要彻底固定端口，请放下一个小 JSON 配置文件。port 以这种方式设置时时它会被钉住——服务器只绑定该端口，绝不自动增大。因此你注册 Claude 一次，URL就不会再变化。

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

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

为什么是 ~/Movies 而不是 ~/.config？ Lite 应用是沙箱化的，只能读取它自己的容器、~/Movies 以及交互式选择的文件——~/.config 在沙箱之外，Lite 无法读取，所以日志里也用了。对于非沙箱 Studio，服务器也会检查 ~/.config/davinci-resolve-lite-mcp/config.json，这是常规位置。

然后重启服务器（脚本 > 工具 > 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 都会 POST 到服务器的 /shutdown 端点，并扫描服务器启动时相同的端口范围。

端口只会在未被固定时才会自动递增（从 8765 开始）。要锁住它，让 URL 在多次启动间保持不变，见配置端口（稳定，推荐）。

工具

163 个工具，涵盖基本管线：

• 状态与导航 — 页面切换、项目/时间线设置

• 项目与时间线 — 加载/创建/复制、标记、场景剪切标记、生命周期

• 轨道 — 添加/删除、启用/锁定/重命名

• 剪辑 — 放置/追加/删除片段、标题与包装器、变换/裁剪/缩放

• 媒体池与存储 — 导入/删除、属性与元数据、标签、媒体浏览

• 颜色 — 节点图 LUT 启用、重置质感、静帧

• 渲染与分层 — 渲染队列、编码器、帧/时间线/项目导出与分享

详见 docs/TOOLS.md。

每次工具调用都会单独记录到 Resolve Console 和日志文件中：[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）则跳过，并给出原因。少数 marker / still 测试依赖一个干净的会话状态，如果它们不稳定，请在刚启动后重跑。

贡献

关于如何添加工具、运行代码套件、仅 stdlib / Lite-first 约束，以及发布流程，见 CONTRIBUTING.md。

范围

这个服务器针对免费（Lite）版，并且刻意只支持在那里运行的 API。Studio 专用 / 付费功能有意忽略（它们在 Lite / Studio 上要么不起作用要么报错），即：音频转写、音频转写、自动字幕、Magic Mask、Stabilize、Smart Reframe、Dolby Vision 分析、Voice Isolation，以及云端项目 / 数据库管理。其余未包起来的都是简单的取值方法（GetUniqueId、缓存模式、内置的 Fusion-composing 内部、take 切换等）。并没有功能缺口。

已知限制

• 片段可通过名称（在当前媒体池文件夹内）或 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。