# Installation and Configuration

This guide covers Resolve requirements, the universal installer, supported MCP clients, server modes, and manual configuration.

## Requirements

- **DaVinci Resolve** 18.5+ (macOS, Windows, or Linux). **Studio** supports
  external scripting directly. The **free edition** does not — Blackmagic gates
  external scripting to Studio — but it is still reachable through the
  [free-edition in-app bridge](../README.md#free-edition-in-app-bridge), which
  runs inside Resolve from the ungated **Workspace ▸ Scripts** menu. Everything
  below assumes Studio unless the bridge is in use
- **Python 3.10+** (the MCP SDK requires 3.10). **3.10–3.12 is the lowest-risk
  choice**; 3.13/3.14 also work on recent Resolve builds — see below
- DaVinci Resolve running with **Preferences > General > "External scripting using"**
  set to **Local**, or **Network** with `RESOLVE_SCRIPT_HOST` set to the Resolve
  host IP (`127.0.0.1` when Resolve and the MCP run on the same machine)

### Optional extras

The core install needs only Python, ffmpeg and the Resolve scripting API.
Several features need an additional package and **refuse with the install line
rather than guessing** if it is absent:

| Extra | Unlocks | Licence |
|---|---|---|
| **ffmpeg** on PATH | silence detection, dead-space markers, level measurement | LGPL/GPL, subprocess only |
| `numpy` | `plan_prebalance`, `plan_reference_match`, `sound_density_audit` | BSD |
| `librosa` | `plan_beat_cuts` (beat / bar / phrase detection) | ISC |
| `openai-whisper` | transcription and the word-level tools built on it | MIT |
| `open_clip_torch` | visual similarity, `find_similar` | MIT |
| `transformers` | CLAP audio embeddings | Apache-2.0 |
| `opencv-python` | additional frame analysis | Apache-2.0 |

`python scripts/doctor.py` reports which are present. `media_analysis`
`capabilities` covers the analysis stack in more detail.

**Install them into the environment the server runs from.** A managed install
uses its own virtualenv, and `pip install` from an unrelated shell puts the
package somewhere that interpreter never looks. Use the venv's own pip —
`<install>/venv/bin/pip` (`venv\Scripts\pip.exe` on Windows) — or activate it
first. Command-line tools that come with a package (`openai-whisper` installs a
`whisper` executable) are found in that venv's script directory automatically
since v2.98.2; before that they had to be on PATH by hand.

Model weights carry their own licences, separate from the code that loads them.

> **Python 3.13 / 3.14:** these are **allowed** — setup will use them and warn.
> Python 3.14 is verified working against DaVinci Resolve Studio 20.3.2. On
> *older* Resolve builds the scripting bridge may fail to load on 3.13+
> (`scriptapp("Resolve")` returns `None`); setup's connection check will tell you
> if that happens. If it does, install a 3.10–3.12 interpreter
> (`brew install python@3.12`, `pyenv install 3.12`, or python.org on Windows) and
> point the launcher at it with `DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12`.

Validated live coverage is based on **DaVinci Resolve 19.1.3 Studio** for the original API surface, plus **DaVinci Resolve 20.3.2 Studio** for the Resolve 20.0-20.2.2 scripting additions. Resolve 21 beta APIs are intentionally deferred until a stable release.

## Quick Start

```bash
# Make sure DaVinci Resolve Studio is running, then:
npx davinci-resolve-mcp setup
```

The npm launcher installs a managed copy in your user application-data directory
and then runs the universal Python installer from there. MCP client configs point
directly at the managed Python virtual environment and `src/server.py`, so Node
is not required after setup.

For source installs:

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

python install.py
```

The universal installer auto-detects your platform, finds your DaVinci Resolve installation, creates a virtual environment, and configures your MCP client — all in one step.

The installer and MCP server perform a best-effort update check against the latest GitHub release. The server check runs in the background, is throttled to once every 24 hours, and never installs code automatically. Set `DAVINCI_RESOLVE_MCP_UPDATE_CHECK=0` to disable it, or `DAVINCI_RESOLVE_MCP_UPDATE_INTERVAL_HOURS` to adjust the interval.

### Supported MCP Clients

The installer can automatically configure any of these clients:

| Client | Config Written To |
|--------|-------------------|
| Antigravity (Google) | `~/.gemini/config/mcp_config.json`, or `~/.gemini/antigravity/mcp_config.json` if that file already exists (all platforms) |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS); `%APPDATA%\Claude\claude_desktop_config.json` (Windows, see MSIX note below) |
| Claude Code | `.mcp.json` (project root) |
| Cursor | `~/.cursor/mcp.json` |
| VS Code (Copilot) | `.vscode/mcp.json` (workspace) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | VS Code global storage |
| Roo Code | VS Code global storage |
| Zed | `~/.config/zed/settings.json` |
| Continue | `~/.continue/config.json` |
| OpenCode | `~/.config/opencode/opencode.json` (or project-root `opencode.json`) |
| Codex CLI | `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) — TOML `[mcp_servers.davinci-resolve]` |
| JetBrains IDEs | Manual (Settings > Tools > AI Assistant > MCP) |

You can configure multiple clients at once, or use `--clients manual` to get copy-paste config snippets.

> **Windows MSIX note (Claude Desktop):** Claude Desktop for Windows is
> distributed as an MSIX package — even when downloaded from the official
> website. MSIX filesystem virtualization redirects the app's config to
> `%LOCALAPPDATA%\Packages\Claude_<publisherhash>\LocalCache\Roaming\Claude\claude_desktop_config.json`,
> and the app never reads the documented `%APPDATA%\Claude\` path (which may
> still exist on disk). The installer detects the virtualized location and
> writes there automatically. If the server does not appear in Claude Desktop
> after a manual setup, check both locations.

For [Autohand Code](https://github.com/autohandai/code-cli/), register the managed launcher after setup:

```bash
autohand mcp add davinci-resolve npx davinci-resolve-mcp server
```

Autohand adds npx's `-y` flag automatically. Add `--scope project` after `mcp add` to keep the registration in the current workspace.

### Installer Options

```bash
npx davinci-resolve-mcp setup                 # Interactive npm setup
npx davinci-resolve-mcp setup --clients all   # Configure all clients
npx davinci-resolve-mcp doctor                # Dry-run environment/config check
npx davinci-resolve-mcp server                # Launch the managed MCP server
npx davinci-resolve-mcp control-panel         # Launch the local control panel
npx davinci-resolve-mcp sync                  # Refresh the managed install only

python install.py                              # Interactive mode
python install.py --clients all                # Configure all clients
python install.py --clients cursor,claude-desktop  # Specific clients
python install.py --clients manual             # Just print the config
python install.py --dry-run --clients all      # Preview without writing
python install.py --no-venv --clients cursor   # Skip venv creation
```

### Server Modes

The MCP server comes in two modes:

| Mode | File | Tools | Best For |
|------|------|-------|----------|
| **Compound** (default) | `src/server.py` | 36 | Most users — fast, clean, low context usage |
| **Full** | `src/resolve_mcp_server.py` | 353 | Power users who want one tool per API method |

The compound server's `timeline_item` tool includes dedicated actions for common workflows:

| Category | Actions | Parameters |
|----------|---------|------------|
| **Retime** | `get_retime`, `set_retime` | process (nearest, frame_blend, optical_flow), motion_estimation (0-6) |
| **Transform** | `get_transform`, `set_transform` | Pan, Tilt, ZoomX/Y, RotationAngle, AnchorPointX/Y, Pitch, Yaw, FlipX/Y |
| **Crop** | `get_crop`, `set_crop` | CropLeft, CropRight, CropTop, CropBottom, CropSoftness, CropRetain |
| **Composite** | `get_composite`, `set_composite` | Opacity, CompositeMode |
| **Audio** | `get_audio`, `set_audio` | Volume, Pan, AudioSyncOffset |
| **Keyframes** | `get_keyframes`, `add_keyframe`, `modify_keyframe`, `delete_keyframe`, `set_keyframe_interpolation` | property, frame, value, interpolation (Linear, Bezier, EaseIn, EaseOut, EaseInOut) |

The installer uses the compound server by default. To use the full server:
```bash
python src/server.py --full    # Launch full 353-tool server
# Or point your MCP config directly at src/resolve_mcp_server.py
```

### Local Control Panel

The repository includes a local, single-user control panel for server status,
Resolve clip visibility, source-safe media-analysis jobs, and the searchable
analysis index. Persisted analysis jobs refresh the index automatically after
successful slices; the manual Build Index action is for rebuilding from existing
reports.

From the repository root:

```bash
venv/bin/python -m src.control_panel
```

This opens the browser by default. Use `--no-open` to run only the localhost
server, or `--port` to choose a different port:

```bash
venv/bin/python -m src.control_panel --no-open --port 8766
```

You can also ask an AI coding agent: **"Open the Resolve MCP control panel for
this repo."** The agent should launch the command above and open the local URL.

### Manual Configuration

If you prefer to set things up yourself, add to your MCP client config:

```json
{
  "mcpServers": {
    "davinci-resolve": {
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/davinci-resolve-mcp/src/server.py"],
      "env": {
        "RESOLVE_SCRIPT_API": "/path/to/DaVinci Resolve/Developer/Scripting",
        "RESOLVE_SCRIPT_LIB": "/path/to/fusionscript.so-or-dll",
        "PYTHONPATH": "/path/to/DaVinci Resolve/Developer/Scripting/Modules"
      }
    }
  }
}
```

Codex CLI uses TOML instead. Add to `~/.codex/config.toml` (or
`$CODEX_HOME/config.toml`):

```toml
[mcp_servers.davinci-resolve]
command = "/path/to/venv/bin/python"
args = ["/path/to/davinci-resolve-mcp/src/server.py"]
env = { RESOLVE_SCRIPT_API = "/path/to/DaVinci Resolve/Developer/Scripting", RESOLVE_SCRIPT_LIB = "/path/to/fusionscript.so-or-dll", PYTHONPATH = "/path/to/DaVinci Resolve/Developer/Scripting/Modules" }
```

Paths must be absolute — Codex does not expand `~`. Run
`python install.py --clients codex` to have the installer write this block for
you (it merges into an existing config and leaves your other servers and
comments alone).

On Windows, installer-generated configs also include `PYTHONHOME`. That scopes Resolve's Python binding to the selected interpreter and avoids the Resolve 20.3 multi-Python crash reported in [Issue #26](https://github.com/samuelgursky/davinci-resolve-mcp/issues/26).

For Resolve's **Network** scripting mode, add
`"RESOLVE_SCRIPT_HOST": "127.0.0.1"` to the `env` object above, replacing the
address when Resolve runs on another host. When this variable is present, the
server uses Resolve's explicit IP-targeted `scriptapp` call with a bounded
connection timeout. Set `RESOLVE_SCRIPT_TIMEOUT` to override the default
five-second timeout with a positive finite number of seconds. The installer
includes both values in generated client configs when they are present in its
environment.

Network scripting permits remote control of Resolve. Prefer Local mode when
remote access is unnecessary; otherwise restrict access with host firewall and
network controls.

Run the read-only doctor against Network mode explicitly:

```bash
python3 scripts/doctor.py --resolve-host 127.0.0.1
python3 scripts/doctor.py --resolve-host resolve.example.test --resolve-timeout 12.5
```

When the compound server is running, `resolve_control(action="get_version")`
includes the local MCP version, the last update-check status, and the current
update decision under the `mcp` key. `resolve_control(action="mcp_update_status",
params={"force_check": true})` performs an explicit foreground check.

### MCP Update Policy

The server keeps update checks non-interactive so MCP stdio startup remains safe
for every client. The installer is the human-facing prompt surface: when a newer
GitHub release is available, interactive installs can update now, continue,
snooze for 24 hours, ignore that release, enable safe auto-update, or disable
checks for the checkout.

Safe auto-update only runs for clean git checkouts with a configured upstream,
and applies `git fetch --tags --prune` followed by `git pull --ff-only`. If the
checkout has local changes, no upstream, or a non-fast-forward update, the
installer continues with the current build.

Installer flags:

```bash
python install.py --update-now
python install.py --update-policy prompt
python install.py --update-policy auto
python install.py --update-policy notify
python install.py --update-policy never
python install.py --clear-update-preferences
```

The same local defaults are available from chat through
`setup(action="get_defaults")` and `setup(action="set_defaults")`. For example,
`{"defaults":{"updates":{"mode":"notify"}}}` changes the MCP update policy
without rerunning the installer. `updates.check_interval_hours` and
`updates.snooze_hours` can also be set from the same setup tool; environment
variables still take precedence when present.

Environment controls:

```bash
DAVINCI_RESOLVE_MCP_UPDATE_CHECK=0
DAVINCI_RESOLVE_MCP_UPDATE_MODE=prompt|auto|notify|never
DAVINCI_RESOLVE_MCP_UPDATE_INTERVAL_HOURS=24
DAVINCI_RESOLVE_MCP_UPDATE_SNOOZE_HOURS=24
DAVINCI_RESOLVE_MCP_UPDATE_STATE=/path/to/update-check.json
```

Platform-specific paths:

| Platform | API Path | Library Path |
|----------|----------|-------------|
| macOS | `/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting` | `fusionscript.so` in DaVinci Resolve.app |
| Windows | `C:\ProgramData\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting` | `fusionscript.dll` in Resolve install dir |
| Linux | `/opt/resolve/Developer/Scripting` | `/opt/resolve/libs/Fusion/fusionscript.so` |