# 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`](https://docs.astral.sh/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:

```bash
uv tool install --force --python 3.11 .
```

Install the authenticated bridge and its private configuration:

```bash
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:

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

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

```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`](.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`](plugins/resolve-studio-control) and a repo
marketplace catalog at [`.agents/plugins/marketplace.json`](.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:

```bash
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](#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/`](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`](docs/openai-submission-packet.md), including the
copy-ready listing, exact reviewer matrix, security facts and hosted-MCP plan.
For setup and incident handling, see the public [`Support`](SUPPORT.md) guide.

## Verification

```bash
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:

```bash
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`](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.