Codex DaVinci Resolve MCP

A local, safety-first MCP server that lets Codex inspect, produce, edit, export, and render videos in DaVinci Resolve through prompts.

The connector has two interchangeable transports:

• Direct for Resolve Studio with local external scripting enabled.
• Authenticated loopback bridge for Resolve Lite/free. Resolve launches a persistent fuscript child on 127.0.0.1; requests use HMAC-SHA256 signatures, timestamp freshness, and one-use nonces, so the shared secret never travels over the socket and captured requests cannot be replayed.

The MCP surface never exposes raw Python, Lua, shell execution, arbitrary Resolve methods, network scripting, or unrestricted filesystem access.

Requirements

• DaVinci Resolve 21; the verified target is Resolve Lite 21.0.2.4 from the Mac App Store.
• Python 3.11 and uv.
• Codex CLI/app for registration.
• FFmpeg and ffprobe only for the live acceptance test.

Production installation

Install a non-editable, workspace-independent server runtime:

uv tool install --force --python 3.11 .

Install the authenticated bridge and its private configuration:

davinci-resolve-bridge-install --workspace "$PWD"

The installer preserves the random token on upgrades, writes configuration files with mode 0600, and deploys applicable macOS targets for a regular Studio install, the all-users Resolve script location, and the sandboxed App Store Lite container.

Restart Resolve. Open a saved project, then choose Workspace → Scripts → Codex Resolve Bridge. The menu is available inside a project, not from the Project Manager. The bridge remains alive until Resolve exits.

Register the stable executable with Codex:

codex mcp add davinci-resolve \
  --env DAVINCI_TRANSPORT=auto \
  -- "$HOME/.local/bin/davinci-resolve-mcp"

Recommended defense-in-depth settings in ~/.codex/config.toml:

[mcp_servers.davinci-resolve]
command = "/ABSOLUTE/PATH/TO/.local/bin/davinci-resolve-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 300
required = false
default_tools_approval_mode = "writes"

[mcp_servers.davinci-resolve.env]
DAVINCI_TRANSPORT = "auto"

[mcp_servers.davinci-resolve.tools.resolve_execute_destructive_action]
approval_mode = "prompt"

Start a new Codex task after registration so it discovers the server. For project-scoped configuration, adapt .codex/config.toml.example.

Supported workflows

The 27 typed MCP tools cover:

• health, project listing, state inspection, production preflight, project creation/open/save, verified DRP backups, and allowlisted settings;
• media import, bins, timeline creation, clip append/placement, tracks, transforms, crop/composite properties, markers, Text+ titles, and LUTs;
• non-destructive, version-named timeline revisions that preserve the source edit;
• render-format/codec discovery, render configuration, queueing, progress, H.264/AAC output, and DRT/OTIO/AAF/EDL/FCPXML/text exports;
• bounded delivery QC using an allowlisted ffprobe executable, including codec, streams, dimensions, frame rate, duration, file size, and optional SHA-256 checks;
• separately prepared and confirmed deletion of projects, timelines, items, media, tracks, markers, and render jobs.

Safe prompting pattern

Ask Codex to call resolve_health and resolve_production_preflight first. For an existing user project, it should export a unique .drp backup and duplicate the working timeline with a versioned name before editing. Provide idempotency keys for additive operations, inspect state after writes, rerun preflight before delivery, and call resolve_verify_media on the rendered file. Deletion is always two-step: resolve_prepare_destructive_action, then resolve_execute_destructive_action with the returned token.

Example:

Open “Product Launch”, run a 1080p/24 delivery preflight, export a versioned DRP backup, duplicate the current timeline as “Product Launch — Edit v004”, and make the requested edits only on that revision. Render H.264/AAC to my allowed output folder, verify the resulting codec, audio, dimensions, frame rate, duration, and file size, then save. Do not overwrite or delete anything.

Configuration

Variable	Default	Meaning
DAVINCI_TRANSPORT	auto	auto, direct, bridge, or guarded mock
DAVINCI_BRIDGE_CONFIG	~/.config/codex-davinci-resolve/bridge.json	Shared bridge configuration and token
DAVINCI_AUDIT_LOG	~/.local/state/codex-davinci-resolve/audit.jsonl	Local security audit log
DAVINCI_TOOL_TIMEOUT_SECONDS	90	Per-request timeout from 1 to 900 seconds
DAVINCI_ENABLE_MOCK	unset	Must equal 1 before mock transport is accepted

The installer creates conservative media/output allowlists. Rerun it with --allow-root or --allow-output-root to add a directory. Paths are canonicalized before authorization, so symlink escapes are rejected. App Store Resolve can reliably access ~/Movies; the live test therefore uses ~/Movies/CodexResolveMCP.

An unsaved transient Resolve project is intentionally not auto-discarded. If resolve_create_project returns unsaved_project_active, save it in Resolve or call resolve_open_project with a known saved project and save_current=false before creating another project.

Render settings are applied in small verified groups. Some documented quality values are codec-specific; render_setting_rejected identifies the exact rejected key rather than silently accepting a partial configuration.

Plugin distribution

This repository includes a Codex plugin bundle under plugins/resolve-studio-control and a repo marketplace catalog at .agents/plugins/marketplace.json. The bundle keeps the MCP server local and starts the installed davinci-resolve-mcp executable; it never exposes the Resolve bridge to the public internet.

For a local checkout, add the repository marketplace and install the plugin:

codex plugin marketplace add /ABSOLUTE/PATH/TO/codex-davinci-resolve-mcp
codex plugin add resolve-studio-control@codex-resolve

The installer prerequisite is Python 3.11 plus DaVinci Resolve. Install the package and bridge first with the commands in Production installation, then start Resolve's Codex Resolve Bridge script. The plugin's resolve-studio skill enforces the preflight, DRP backup, versioned timeline and delivery-QC loop.

The public release site is generated from site/ and deployed through GitHub Pages. This is an independent integration and is not affiliated with Blackmagic Design.

Publication materials are collected in the OpenAI submission packet, including the copy-ready listing, exact reviewer matrix, security facts and hosted-MCP plan. For setup and incident handling, see the public Support guide.

Verification

uv sync --all-extras --frozen
PYTHONPATH=src .venv/bin/ruff format --check .
PYTHONPATH=src .venv/bin/ruff check .
PYTHONPATH=src .venv/bin/mypy src scripts/live_e2e.py
PYTHONPATH=src .venv/bin/pytest
PYTHONPATH=src .venv/bin/python scripts/contract_check.py
uv build
uv export --frozen --no-dev --no-hashes --no-emit-project --format requirements.txt | \
  uvx pip-audit --requirement /dev/stdin --progress-spinner off --strict

Live verification is intentionally separate. Create and open a saved empty project named Codex MCP Bridge Bootstrap ..., start the bridge, then run:

PYTHONPATH=src .venv/bin/python scripts/live_e2e.py

The harness generates deterministic A/V fixtures, communicates only through real MCP stdio calls, exports and verifies a DRP backup, creates a versioned timeline revision, runs studio preflight, verifies persisted edits, renders, performs MCP delivery QC plus an independent ffprobe check, exports DRT, deletes only its unique Codex MCP E2E ... project through a scoped confirmation token, and restores the bootstrap project.

See SPEC.md for the contract and acceptance gates.

Troubleshooting

• Scripts shows “No Scripts”: restart Resolve after installation and open a saved project before checking Workspace → Scripts.
• bridge_not_running: run Codex Resolve Bridge from the Workspace menu.
• bridge_timeout: inspect Resolve for a modal. If its native API remains blocked, restart Resolve and the bridge.
• direct_unavailable: expected on Resolve Lite; DAVINCI_TRANSPORT=auto falls back to the authenticated bridge.
• Render setting rejected: call resolve_get_render_options, use returned API tokens, and omit codec-specific settings that the selected codec rejects.