DaVinci Resolve MCP Server

English | 简体中文

Сервер Model Context Protocol (MCP), который позволяет AI-ассистентам управлять DaVinci Resolve Studio через официальный Scripting API. Он обеспечивает полное покрытие API, а также защищённые вспомогательные инструменты для редактирования, организации медиапула, настройки рендеринга, маркеров ревью, грейдинга, Fusion, Fairlight, задач жизненного цикла проектов, создания расширений и безопасного для исходников анализа медиа.

С сервером поставляется локальная браузерная панель управления для просмотра состояния Resolve, выполнения безопасного для исходников анализа, детального изучения проанализированных клипов и кадров, а также инлайн-редактирования результатов анализа. Полный обзор см. в Руководстве по панели управления.

Быстрый старт

npx davinci-resolve-mcp setup

Перед подключением откройте DaVinci Resolve Studio и установите Настройки > Общие > Внешний скриптинг на Локально. (В бесплатной версии эта настройка не помогает — см. Бесплатная версия ниже.) npm-установщик устанавливает управляемую копию в каталог пользовательских данных приложения, а затем запускает универсальный Python-установщик. Установщик создаёт виртуальное окружение, определяет пути Resolve и может настроить Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, Cline, Roo Code, OpenCode, Codex CLI и JetBrains IDEs.

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

Информацию о путях для платформ, конфигурации для конкретных клиентов и ручной настройке см. в Установка и настройка.

Установщик и сервер проверяют последний релиз GitHub на наличие обновлений MCP. Проверки выполняются по мере возможности и с ограничением частоты; сервер никогда не блокирует запуск MCP ради запроса. Установщик может показать запрос, отложить, проигнорировать релиз, отключить проверки или применить добровольное безопасное автоматическое обновление для чистых git-клонов.

Бесплатная версия (мост внутри приложения)

Blackmagic ограничивает внешний скриптинг версией Studio: в бесплатной версии scriptapp("Resolve") отказывает внешнему процессу, что бы ни говорила настройка. Меню Рабочая область ▸ Скрипты не ограничено — скрипт, запущенный из него, получает живой объект resolve в любой версии, — поэтому сервер может работать с бесплатной версией через небольшой скрипт, который выполняется внутри Resolve и реэкспортирует его через аутентифицированный loopback-слушатель.

python scripts/install_resolve_bridge.py
# restart Resolve, open a project, then: Workspace > Scripts > resolve_bridge

Как только этот слушатель запущен, он используется автоматически, когда внешний скриптинг недоступен — переменная окружения не требуется. Установка DAVINCI_RESOLVE_BRIDGE=1 принудительно включает мост: он становится единственным используемым транспортом, поэтому мост, переставший отвечать, сообщает о собственной ошибке, а не незаметно переключается на другой транспорт. Используйте это, когда мост — тот путь, на который вы хотите полагаться.

В macOS Resolve ищет Python 3 ровно в двух местах: переменная окружения PYTHON3HOME, затем /usr/local/bin/python3. Homebrew, pyenv, uv и conda не попадают ни в одно из них, поэтому скрипт молча не появляется в меню. Установка с python.org работает, потому что её установщик создаёт /usr/local/bin/python3 — но он вам не нужен: укажите Resolve на уже имеющийся интерпретатор, sudo не требуется.

launchctl setenv PYTHON3HOME "$(python3 -c 'import sys; print(sys.prefix)')"

Используйте launchctl setenv, а не export — Resolve запускается из Dock и никогда не видит окружение вашего shell. После этого перезапустите Resolve. Рядом устанавливается Lua-канарейка, чтобы можно было отличить «Python не обнаружен» от неправильной папки.

Проверено на бесплатной версии 21.0.3.7 и Studio 19.1.3.7, обе на macOS. Пути для Windows, добавленные в v2.70.1 (issue #106), были опубликованы без проверки; отчёты о бесплатных версиях 21.0.1.11 (issue #109) и 21.0.3.7 (issue #112) с тех пор показали, что мост устанавливается, перечисляется и работает из обоих %PROGRAMDATA% и %APPDATA% в Windows 11, так что эти пути теперь подтверждены, а не предполагаемы. Linux также подтверждён: отчёт о бесплатной версии 20.3.2.9 (issue #129, Fedora 43) показывает, что мост устанавливается в ~/.local/share/DaVinciResolve/Fusion/Scripts/Utility, работает со системным Python — в Linux нет этой проблемы обнаружения — и обслуживает запросы от начала до конца. Ни одна платформа теперь не основана на предположении: macOS была проверена напрямую, Windows и Linux — на отчётах пользователей.

Обратите внимание: мост удерживает свой порт, пока работает. До v2.70.3 мост в Windows мог пережить Resolve и заблокировать слушатель следующего сеанса; если у вас старая сборка и мост перестал отвечать, проверьте, не удерживает ли порт устаревший fuscript.exe.

Это документированный путь внутри приложения, а не обход лицензии, но Blackmagic может его закрыть — относитесь к нему как к уровню поддержки, который действует, пока действует. Только loopback, запросы с HMAC-подписью, одноразовые nonce-значения.

Локальная панель управления

Запустите однопользовательскую локальную панель управления из корня репозитория:

venv/bin/python -m src.control_panel

Команда запускает локальный сервер localhost и открывает панель управления в вашем браузере. Чтобы это сделал AI-агент кодирования, попросите: «Открой панель управления Resolve MCP для этого репозитория». Агенты должны использовать venv/bin/python -m src.control_panel, если ваше окружение Python ещё не активировано. Сохранённые задания анализа автоматически обновляют локальный поисковый индекс после успешных фрагментов; ручное действие Build Index предназначено для пересоздания из существующих отчётов.

Режимы сервера

Рекомендуется использовать комбинированный сервер, если только вам не нужна именно детальная поверхность «один инструмент на метод».

Продвинутый сервер — за пределами scripting API (опционально, Node)

Тот же пакет включает второй, опциональный MCP-сервер: davinci-resolve-advanced-mcp (бинарник bin/davinci-resolve-advanced-mcp.mjs). В то время как Python-сервер управляет живым Resolve через официальный scripting API, продвинутый сервер делает то, что API не может, — он читает и редактирует файлы Resolve (.drp / .drt / .drx) и применяет изменения на уровне БД/XML без запущенного Resolve, поэтому работает в облаке или локально. 18 инструментов: drp, drt, drx (поклиповый грейд-кодек плюс детерминированный офлайн-каталог грейдинга/QC — сопоставление тонов кожи в пределах камеры и между камерами (метрика v2 skin-line) + b-roll + нейтральный патч для баланса белого, подгонка к референсу, насыщенность/баланс чёрного, нормализация контраста, импорт ASC CDL, без потерь перенос грейда + создание сезонного лука, прикрепление именованных LUT, чтение скоупов + теги намерений, проверка грейда, извлечение кадров в display-referred, QC на соответствие вещательным стандартам), offline_ref, conform (frame-oracle сверка/перелинковка QC + происхождение), color_trace (перенос грейдов при повторном конформе), fusion, audio_plan, fairlight (маршрутизация шин), audio, project_read, project_db, pipeline (конвейер с БД как источником истины: компиляция YAML-спецификаций проекта в каноническую SQLite-БД, затем выполнение стадий с шлюзами, происхождением и обнаружением расхождений намерение↔факт), capabilities, deliverable (QC/соответствие требованиям deliverable), media (медиа-фронтенд / AE-ингest), editorial (целостность монтажа / список изменений), provenance (происхождение / аудит / отчёт по эпизоду). Его также можно использовать как библиотеку (импортируемый движковый API), а не только запускать как сервер.

Запись грейдов DRX калибруется в реальном времени по Resolve Studio: параметры грейда по умолчанию принимают единицы экранных панелей Resolve (space: 'ui' | 'drx'), а структурные записи (power windows, квалификаторы, HDR-зоны, HSL-кривые, ColorSlice, blur/key/эффекты движения) проверяются обратным считыванием с панелей — статус по каждому элементу управления в resolve-advanced/vendor/drx-parameters/CALIBRATION-STATUS.md. Это также закрывает разрыв, существующий только в UI: программная «Очистка графа узлов» (drx relayout для одного клипа, project_db relayout_node_graphs для всего проекта) — раскладка узлов приведена в порядок, содержимое грейда сохранено побайтово.

Добавьте его рядом с живым сервером (оба поставляются в одном npm install):

{
  "mcpServers": {
    "davinci-resolve": { "command": "<python>", "args": ["<path>/src/server.py"] },
    "davinci-resolve-advanced": { "command": "node", "args": ["<path>/bin/davinci-resolve-advanced-mcp.mjs"] }
  }
}

install.py выводит оба пункта. Ядро — чистый JS/MIT без обязательных нативных модулей; для некоторых функций требуются устанавливаемые пользователем инструменты (ffmpeg для audio, sharp/better-sqlite3 для некоторых путей) — вызовите инструмент capabilities, чтобы узнать актуальный статус и подсказки по установке.

Bradford Post Assistant — управляемое приложение (закрытая бета)

Сопровождающие также создают Bradford Post Assistant — десктопное приложение поверх этой открытой основы. Если MCP-серверы дают агенту руки, Post Assistant — это рабочий копайлот вокруг них — локальный AI-ассистент для постпродакшена, в котором клиентские материалы никогда не покидают рабочую станцию:

• Постпродакшен-копайлот — десктопное приложение, которое работает рядом с DaVinci Resolve и наблюдает за сеансом в реальном времени (таймлайн, грейды и кадры — не только вызовы API), со встроенным AI-ассистентом и средой выполнения агента, локальным анализом медиа (транскрипция, анализ кадров, редакционная аналитика) и встроенным QC конформа.

• Память — постоянная, зашифрованная локальная память ассистента плюс межэпизодное обучение на основе декодированных фактов из вашего конвейера (сезонный дрейф лука, априорные поправки для каждой камеры, библиотеки hero-кадров, повторное использование карты путей конформа), с накоплением, управляемым за вас, и рабочим процессом проверенных инсайтов.

• Самодостаточен по замыслу — Post Assistant сам всё подключает: этот MCP для управления Resolve, Bradford API для расширенных сервисов и вашего провайдера LLM. Ничего не нужно настраивать вручную, не нужно управлять отдельными клиентами, а приложение само поддерживает актуальность себя (и своего встроенного MCP) с помощью подписанных автоматических обновлений.

• Расширенный профессиональный инструментарий — хирургическая работа с грейдами в живых проектах, более 22 адаптивных семейств грейдов, курируемая библиотека луков, проверка спецификаций доставки, анализ монтажного темпа/чистки, цветовые указания на естественном языке и создание Fusion-композиций — всё через управляемый Bradford API.

• Производственные процессы — сырые инструменты, собранные в готовые реальные сценарии (передача → конформ → QC → доставка, перенос сезонного лука, отчётность по эпизодам) с защитными ограничениями и утверждениями, которых ожидает студия, работающая с клиентами.

Сейчас он находится в закрытой бете — вы можете запросить доступ на bradfordoperations.com/software/post-assistant. Серверы с открытым исходным кодом полностью готовы и полностью функциональны сами по себе.

Что вы можете делать

"List all projects and open the one called 'My Film'"
"Create a timeline called 'Assembly Cut' from all clips in the current bin"
"Build a multicam prep timeline from selected camera angles and preserve source media"
"Detect 2-pops or slate claps and suggest record offsets for sync prep"
"Publish analysis summaries, keywords, people, and slate hints into Resolve clip metadata"
"Probe this timeline for gaps, overlaps, missing media, and source frame ranges"
"Safely import this image sequence, organize it into bins, and normalize clip metadata"
"Build a ProRes 422 HQ render plan, validate the settings, and queue the job"
"Copy review markers from the timeline to the selected clip and export a review report"
"Snapshot this clip's grade, validate a CDL update, and export a temp LUT"
"Create a Fusion TextPlus overlay on the selected clip and verify graph connections"
"Report audio channel mappings, voice isolation availability, and subtitle support"
"Install this MCP-marked DCTL or script, classify refresh/restart needs, then remove it"

Основные возможности

Дополнительные опции

Базовая установка намеренно небольшая: Python, ffmpeg и скриптовый API Resolve. Некоторым функциям нужно больше, и каждая из них честно отказывается, сообщая собственную команду установки, а не деградирует в догадку — выдуманный темп или изобретённый уровень дают уверенный, но неверный результат, что хуже, чем отсутствие функции.

Запустите python scripts/doctor.py, чтобы узнать, какие из них у вас есть.

Параметр capabilities действия media_analysis подробно сообщает о стеке анализа и говорит, что дал бы каждый отсутствующий компонент.

Здесь ничего не входит в комплект. Веса моделей имеют собственные лицензии, отдельные от кода, который их загружает; проверяйте их перед коммерческим использованием.

Что это не делает

Знать, где заканчивается инструмент, стоит столько же, сколько знать, что он делает, и прочитать об этом здесь дешевле, чем обнаружить посреди проекта.

Всё, что проанализировано, но не поддаётся проверке, помечается как непроверенное и никогда не заносится в разряд «нормально». Пустой результат означает «ничего не найдено», а не «нечего искать».

Безопасность исходных материалов

Этот проект рассматривает оригиналы с камер и исходные материалы как неизменяемые. Инструменты анализа читают исходные файлы и записывают отчёты только в сайдкары, временные каталоги или каталоги анализа проекта; подтверждённая публикация метаданных записывается только в базу данных проекта Resolve. Сервер не должен изменять, перекодировать, создавать прокси или производные от исходных материалов, если пользователь явно не попросил об этом. Подробный безопасный для исходников рабочий процесс см. в Руководстве по анализу медиа.

Модель безопасности

Сервер по умолчанию — локальный stdio-процесс, запускаемый вашим MCP-клиентом; он не предоставляет сетевого слушателя или встроенного механизма многопользовательской аутентификации. Метаданные инструментов содержат подсказки безопасности для MCP-клиента: операции только для чтения, разрушительные, идемпотентные и операции с внешними ресурсами. См. Политику безопасности о границах эксплуатации, правилах подтверждения и сообщении об уязвимостях.

Ключевые показатели

Для статуса по каждому методу см. Покрытие API и результаты тестирования. Для текущей поддержки рабочих процессов см. Покрытие действий ядра.

analyze_media по умолчанию выполняется напрямую, сохраняет проверяемые отчёты/артефакты в корневом каталоге анализа, запрашивает визуальный анализ в хост-чате через протокол host_chat_paths (analyze возвращает абсолютные пути к кадрам + JSON-схему; хост-чат читает каждый кадр как изображение и вызывает media_analysis(action="commit_vision", ...) для завершения), выполняет транскрипцию через настроенный локальный бэкенд и записывает сводки анализа и маркеры клипов Media Pool по времени исходника обратно в проект Resolve. Передавайте include_visuals=false, include_transcription=false, publish_metadata=false, timed_markers=no или dry_run=true только тогда, когда вы хотите отказаться от этих поведений по умолчанию. Пропуск commit_vision оставляет запуск в состоянии pending_host_vision_analysis — это фиксируется как режим сбоя, а не молча понижается.

Документация

Справочники по созданию расширений находятся в docs/authoring. Заметки о пакетах разработчика Resolve — в docs/notes и docs/integrations. Рецепты промптов — в examples.

Требования

• DaVinci Resolve 18.5+ на macOS, Windows или Linux. Studio поддерживает внешние скрипты напрямую. Бесплатная версия — нет: Blackmagic ограничивает внешние скрипты версией Studio, но до неё всё ещё можно добраться через встроенный мост, который работает внутри Resolve из доступного меню Рабочее пространство ▸ Скрипты.

• Python 3.10+ (диапазон 3.10-3.12 — наименее рискованный). Python 3.13/3.14 также работают на свежих сборках Resolve (проверено на Studio 20.3.2); старые сборки могут не подключиться на 3.13+, в этом случае используйте 3.10-3.12.

• Внешние скрипты Resolve должны быть установлены в режим Local (Studio). В бесплатной версии этот параметр не влияет — вместо этого используйте встроенный мост.

Resolve 19.1.3 остаётся базовым уровнем совместимости. Вызовы скриптов Resolve 20.x являются дополнительными, версионно-защищёнными и протестированы вживую на 20.3.2. Дополнения скриптов Resolve 21.0 (классификация аудио, транскрипция с определением говорящего, IntelliSearch, анализ слейта, подавление размытия движения, генерация речи, управление фоновыми задачами сеанса) доступны через определение возможностей во время выполнения, поэтому они остаются неактивными на старых сборках и автоматически активируются на Resolve 21+. Они протестированы вживую на Studio 21.0.2.4 — см. дельту Resolve 21. Обратите внимание, что AnalyzeForIntellisearch, AnalyzeForSlate и GenerateSpeech требуют отдельно загружаемый пакет AI Extras, и Resolve сообщает об отсутствии пакета непоследовательно (некоторые возвращают False, другие — строку ошибки), поэтому эти действия сообщают success: false с причиной от Resolve, а не угадывают.

Разработка

python src/server.py          # Compound server
python src/server.py --full   # Granular server
venv/bin/python tests/test_import.py
venv/bin/python scripts/audit_api_parity.py

Правила выпуска и проверки находятся в docs/process/release-process.md. AI-агенты, работающие в этом репозитории, должны начинать с AGENTS.md; пользователи Claude Code также могут прочитать CLAUDE.md, который указывает на те же канонические инструкции.

Лицензия

MIT

Автор

Samuel Gursky (samgursky@gmail.com)

• GitHub: github.com/samuelgursky

Благодарности

• Blackmagic Design за DaVinci Resolve и его API для скриптов

• Команда Model Context Protocol за обеспечение интеграции AI-ассистентов