DaVinci Resolve MCP Server

一个模型上下文协议（MCP）服务器，将AI编码助手（Cursor、Claude Desktop）连接到DaVinci Resolve，使它们能够通过自然语言查询和控制DaVinci Resolve。

功能

有关已实现和计划功能的完整列表，请参阅 docs/FEATURES.md。

要求

• macOS 或 Windows 并安装了DaVinci Resolve
• Python 3.6+
• 在后台运行的DaVinci Resolve
• （可选）Node.js/npm 用于某些功能

安装指南

有关详细的安装说明，请参阅 INSTALL.md。本指南涵盖：

• 前置条件和系统要求
• 逐步安装过程
• 配置详情
• 常见故障排除步骤

平台支持

快速入门指南

新的一键安装（推荐）

最简单的方法是使用我们的新统一安装脚本。此脚本会自动完成所有操作：

• 克隆仓库：

  bash 复制代码

  git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
  cd davinci-resolve-mcp

• 确保已安装并运行DaVinci Resolve Studio

• 运行安装脚本：
  macOS/Linux:

  bash 复制代码

  ./install.sh

  Windows:

  batch 复制代码

  install.bat

这将：

1. 自动检测系统上的正确路径
2. 创建Python虚拟环境
3. 从官方仓库安装MCP SDK
4. 设置环境变量
5. 配置Cursor/Claude集成
6. 验证安装是否正确
7. 可选地启动MCP服务器

替代快速启动

您也可以使用原始快速启动脚本：

Windows 用户:

run-now.bat

macOS 用户:

chmod +x run-now.sh
./run-now.sh

配置

有关DaVinci Resolve MCP与不同AI助手客户端（如Cursor或Claude）的配置，请参阅 config-templates 目录。

故障排除

有关详细的故障排除指南，请参阅 INSTALL.md 文件，其中包含常见问题的解决方案。

常见问题

路径解析

• 安装脚本现在使用更强大的路径解析，修复了run-now.sh在错误位置查找文件的问题
• 始终让脚本根据其位置确定正确的路径

DaVinci Resolve 检测

• 我们改进了进程检测以可靠地找到DaVinci Resolve，无论它在进程列表中如何显示
• 在启动MCP服务器之前确保DaVinci Resolve正在运行

环境变量

• 确保所有必需的环境变量都设置正确
• 查看日志文件 scripts/cursor_resolve_server.log 以进行故障排除

Windows

• 确保在配置文件中使用正斜杠 (/)
• Python必须安装并且路径已在配置中设置
• 在启动服务器之前，DaVinci Resolve必须正在运行

macOS

• 确保脚本具有执行权限
• 在Console.app中检查任何与Python相关的错误
• 验证环境变量是否设置正确
• 在启动服务器之前，DaVinci Resolve必须正在运行

支持

有关问题和功能请求，请使用GitHub问题跟踪器。

启动选项

安装后，您可以有几种方式启动服务器：

客户端特定启动脚本

仓库中包含专门用于启动特定客户端的脚本：

# 对于Cursor集成 (macOS)
chmod +x scripts/mcp_resolve-cursor_start
./scripts/mcp_resolve-cursor_start

# 对于Claude Desktop集成 (macOS)
chmod +x scripts/mcp_resolve-claude_start
./scripts/mcp_resolve-claude_start

这些专用脚本：

• 为每个客户端设置适当的环境
• 验证DaVinci Resolve是否正在运行
• 配置客户端特定的设置
• 使用适当的参数启动MCP服务器

启动前检查

在连接AI助手之前，验证您的环境是否配置正确：

# 在macOS上
./scripts/check-resolve-ready.sh

# 在Windows上
./scripts/check-resolve-ready.bat

这些脚本将：

• 验证DaVinci Resolve是否正在运行（并提供启动它的选项）
• 检查环境变量是否设置正确
• 确保Python环境配置正确
• 验证Cursor/Claude配置
• 可选地启动Cursor

统一启动器

对于高级用户，我们的统一启动器提供了对Cursor和Claude Desktop服务器的完全控制：

# 让脚本可执行 (仅限macOS)
chmod +x scripts/mcp_resolve_launcher.sh

# 以交互模式运行
./scripts/mcp_resolve_launcher.sh

# 或者使用命令行选项
./scripts/mcp_resolve_launcher.sh --start-cursor    # 启动Cursor服务器 (使用mcp_resolve-cursor_start)
./scripts/mcp_resolve_launcher.sh --start-claude    # 启动Claude Desktop服务器 (使用mcp_resolve-claude_start)
./scripts/mcp_resolve_launcher.sh --start-both      # 启动两个服务器
./scripts/mcp_resolve_launcher.sh --stop-all        # 停止所有运行中的服务器
./scripts/mcp_resolve_launcher.sh --status          # 显示服务器状态

其他选项：

• 强制模式（跳过Resolve运行检查）：--force
• 项目选择：--project "Project Name"

完全安装

完整的手动安装步骤如下：

1. 克隆此仓库：

   bash 复制代码

   git clone https://github.com/samuelgursky/davinci-resolve-mcp.git
   cd davinci-resolve-mcp

2. 创建Python虚拟环境：

   bash 复制代码

   # 创建虚拟环境
   python -m venv venv
   
   # 激活它
   # 在macOS/Linux上:
   source venv/bin/activate
   # 在Windows上:
   venv\Scripts\activate
   
   # 从requirements.txt安装依赖项
   pip install -r requirements.txt
   
   # 或者直接安装MCP SDK
   pip install git+https://github.com/modelcontextprotocol/python-sdk.git

3. 设置DaVinci Resolve脚本环境变量：

   对于macOS:

   bash 复制代码

   export RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting"
   export RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so"
   export PYTHONPATH="$PYTHONPATH:$RESOLVE_SCRIPT_API/Modules/"

   对于Windows:

   cmd 复制代码

   set RESOLVE_SCRIPT_API=C:\ProgramData\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting
   set RESOLVE_SCRIPT_LIB=C:\Program Files\Blackmagic Design\DaVinci Resolve\fusionscript.dll
   set PYTHONPATH=%PYTHONPATH%;%RESOLVE_SCRIPT_API%\Modules

   或者运行预启动检查脚本，它将为您设置这些：

   复制代码

   # 在macOS上
   ./scripts/check-resolve-ready.sh
   
   # 在Windows上
   ./scripts/check-resolve-ready.bat

4. 通过创建配置文件来配置Cursor以使用服务器：

   对于macOS (~/.cursor/mcp.json):

   json 复制代码

   {
     "mcpServers": {
       "davinci-resolve": {
         "name": "DaVinci Resolve MCP",
         "command": "/path/to/your/venv/bin/python",
         "args": [
           "/path/to/your/davinci-resolve-mcp/src/main.py"
         ]
       }
     }
   }

   对于Windows (%APPDATA%\Cursor\mcp.json):

   json 复制代码

   {
     "mcpServers": {
       "davinci-resolve": {
         "name": "DaVinci Resolve MCP",
         "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
         "args": ["C:\\path\\to\\davinci-resolve-mcp\\src\\main.py"]
       }
     }
   }

5. 使用其中一个客户端特定脚本来启动服务器：

   bash 复制代码

   # 对于Cursor
   ./scripts/mcp_resolve-cursor_start
   
   # 对于Claude Desktop
   ./scripts/mcp_resolve-claude_start

使用AI助手

使用Cursor

1. 使用专用脚本启动Cursor服务器：

   bash 复制代码

   ./scripts/mcp_resolve-cursor_start

   或者使用通用启动器：

   bash 复制代码

   ./scripts/mcp_resolve_launcher.sh --start-cursor

2. 启动Cursor并打开一个项目。

3. 在Cursor的AI聊天中，您现在可以与DaVinci Resolve互动。尝试以下命令：

   • "当前运行的是哪个版本的DaVinci Resolve？"
   • "列出DaVinci Resolve中的所有项目"
   • "创建一个新的时间线叫'My Sequence'"
   • "在当前位置添加一个标记"

使用Claude Desktop

1. 在您的Claude Desktop配置目录中创建一个claude_desktop_config.json文件，使用config-templates目录中的模板。

2. 使用专用脚本运行Claude Desktop服务器：

   bash 复制代码

   ./scripts/mcp_resolve-claude_start

   或者使用通用启动器：

   bash 复制代码

   ./scripts/mcp_resolve_launcher.sh --start-claude

3. 在Claude Desktop中，您现在可以使用与Cursor相同的命令与DaVinci Resolve互动。

可用功能

通用

• 获取DaVinci Resolve版本
• 获取/切换当前页面（编辑、色彩校正、Fusion等）

项目管理

• 列出可用项目
• 获取当前项目名称
• 按名称打开项目
• 创建新项目
• 保存当前项目

时间线操作

• 列出所有时间线
• 获取当前时间线信息
• 创建新时间线
• 按名称切换到时间线
• 向时间线添加标记

媒体池操作

• 列出媒体池剪辑
• 导入媒体文件
• 创建媒体箱
• 将剪辑添加到时间线

Windows支持注意事项

Windows支持在v1.3.3中稳定，不应需要额外的故障排除：

• 确保DaVinci Resolve安装在默认位置
• 如上所述正确设置环境变量
• 根据您的安装情况可能需要调整Windows路径
• 如果出现问题，请检查logs/目录中的日志

故障排除

DaVinci Resolve连接

在启动服务器之前确保DaVinci Resolve正在运行。如果服务器无法连接到Resolve，请检查：

1. 您的环境变量是否设置正确
2. 您是否有正确的DaVinci Resolve安装路径
3. 在设置环境变量后是否重新启动了终端

项目结构

davinci-resolve-mcp/
├── README.md               # 此文件
├── docs/                   # 文档
│   ├── FEATURES.md         # 功能列表和状态
│   ├── CHANGELOG.md        # 版本历史
│   ├── VERSION.md          # 版本信息
│   ├── TOOLS_README.md     # 工具文档
│   ├── PROJECT_MCP_SETUP.md # 项目设置指南
│   └── COMMIT_MESSAGE.txt  # 最近提交的信息
├── config-templates/       # 配置模板
│   ├── sample_config.json  # 示例配置
│   ├── cursor-mcp-example.json # Cursor配置示例
│   └── mcp-project-template.json # MCP项目模板
├── scripts/                # 实用脚本
│   ├── tests/              # 测试脚本
│   │   ├── benchmark_server.py # 性能测试
│   │   ├── test_improvements.py # 测试脚本
│   │   ├── test_custom_timeline.py # 时间线测试
│   │   ├── create_test_timeline.py # 创建测试时间线
│   │   ├── test-after-restart.sh # 重启后的测试 (Unix)
│   │   └── test-after-restart.bat # 重启后的测试 (Windows)
│   ├── batch_automation.py # 批量自动化脚本
│   ├── restart-server.sh   # 服务器重启脚本 (Unix)
│   ├── restart-server.bat  # 服务器重启脚本 (Windows)
│   ├── run-now.sh          # 快速启动脚本 (Unix)
│   └── run-now.bat         # 快速启动脚本 (Windows)
├── resolve_mcp_server.py   # 主服务器实现
├── src/                    # 源代码
│   ├── api/                # API实现
│   ├── features/           # 功能模块
│   └── utils/              # 实用函数
├── logs/                   # 日志文件
├── tools/                  # 开发工具
├── assets/                 # 项目资源
└── examples/               # 示例代码

许可证

MIT

致谢

• Blackmagic Design 提供了DaVinci Resolve及其API
• MCP协议团队实现了AI助手集成

作者

Samuel Gursky (samgursky@gmail.com)

• GitHub: github.com/samuelgursky

未来计划

• Windows和Linux支持
• 更多DaVinci Resolve功能
• 支持Claude Desktop

开发

如果您想贡献代码，请查看仓库中的功能清单并选择一个未实现的功能进行开发。代码结构清晰，分为不同的功能区域。

许可证

MIT

致谢

• Blackmagic Design 提供了DaVinci Resolve及其API
• MCP协议团队实现了AI助手集成

项目结构

清理后，项目具有以下结构：

• resolve_mcp_server.py - 主MCP服务器实现
• run-now.sh - 快速启动脚本，处理设置并运行服务器
• setup.sh - 完整安装脚本
• check-resolve-ready.sh - 启动前检查以验证DaVinci Resolve是否准备就绪
• start-server.sh - 启动服务器的脚本
• run-server.sh - 简化直接运行服务器的脚本

关键目录：

• src/ - 源代码和模块
• assets/ - 项目资产和资源
• logs/ - 日志文件目录
• scripts/ - 辅助脚本

在开发时，建议使用./run-now.sh，它会设置环境并在一步中启动服务器。

更新日志

请参阅 docs/CHANGELOG.md 以获取详细的历史更改记录。

Cursor特定设置

当与Cursor集成时，请按照以下具体步骤操作：

1. 在启动Cursor之前确保DaVinci Resolve正在运行

2. 安装所需的依赖项：

   bash 复制代码

   # 从davinci-resolve-mcp目录：
   pip install -r requirements.txt

   注意：这将自动安装MCP包和其他依赖项。

3. 在Cursor中设置MCP服务器配置：

   创建或编辑macOS上的 ~/.cursor/mcp.json（或Windows上的 %USERPROFILE%\.cursor\mcp.json）：

   json 复制代码

   {
     "mcpServers": {
       "davinci-resolve": {
         "name": "DaVinci Resolve MCP",
         "command": "/path/to/your/venv/bin/python",
         "args": [
           "/path/to/your/davinci-resolve-mcp/src/main.py"
         ]
       }
     }
   }

   重要注意事项：

   • 使用main.py作为入口点（而不是resolve_mcp_server.py）
   • 在配置中使用绝对路径

4. 常见问题：

   • "客户端关闭"错误：检查mcp.json中的路径是否正确且依赖项已安装
   • 连接问题：确保在启动Cursor之前DaVinci Resolve正在运行
   • 环境变量：main.py脚本将处理设置环境变量