# resolve-mcp

An MCP server that gives an AI assistant control of **DaVinci Resolve Studio** on macOS.

**132 tools** across projects, media, timelines, colour, rendering and Fusion — plus
`resolve_exec` for anything the curated tools miss, and `resolve_ui` for the handful of
operations Blackmagic never exposed to scripting at all.

```
"Import this folder, build a timeline in filename order, add a marker at every
 scene cut, then queue ProRes and H.264 renders and tell me when they're done."
```

## Install

Requires macOS, **DaVinci Resolve Studio** (external scripting is a Studio feature),
Python 3.13+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/irstone-source/resolve-mcp.git
cd resolve-mcp
uv sync
uv run python scripts/smoke.py     # verify the connection before wiring anything up
```

Then register with Claude Code:

```bash
claude mcp add resolve -- uv run --directory /absolute/path/to/resolve-mcp resolve-mcp
```

> **One manual step, once.** In Resolve: Preferences → System → General →
> **External scripting using: `Local`**. No API can set it, and without it nothing works.
> Full detail in [docs/SETUP.md](docs/SETUP.md).

## Documentation

| | |
|---|---|
| [Setup](docs/SETUP.md) | Requirements, permissions, headless mode |
| [Tool reference](docs/TOOLS.md) | All 132 tools and 6 resources, generated from the server |
| [Architecture](docs/ARCHITECTURE.md) | How it works and why it's built this way |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Failure modes and Resolve's undocumented behaviour |
| [Development](docs/DEVELOPMENT.md) | Adding tools, testing, conventions |

## How to drive it

Reach for capabilities in this order:

1. **A curated tool** — `project_*`, `media_*`, `timeline_*`, `track_*`, `marker_*`,
   `clip_*`, `lut_*`, `render_*`, `fusion_*`. Typed, validated, with actionable errors.
2. **`resolve_exec`** — arbitrary Python against the live connection, for the long tail of
   the API. The installed scripting reference is served as MCP resources, so calls are
   written against real signatures rather than recalled ones.
3. **`resolve_ui`** — AppleScript menu clicks and keystrokes. Only where no API exists.

### Handles

Resolve returns live objects that can't be sent as JSON, so clips, timeline items, folders
and stills pass between calls as handles:

```
clip:1a2b3c      a media pool clip
item:0091        a clip on a timeline
folder:root      a bin
timeline:4f2a    a timeline
still:2b70       a gallery still
```

Objects returned by `resolve_exec` get handles too, so escape-hatch code composes with the
curated tools.

### Every tool returns the same envelope

```json
{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "No timeline is currently open",
                "hint":  "Create a timeline with timeline_create, or select one with timeline_set_current." }
```

The Resolve API signals failure by returning bare `False` or `None` with no explanation.
This server converts each known cause into a named condition with a remedy, so a failed
call tells you what to do next instead of merely that something went wrong.

## What it's good at

Repetitive and generative work: batch operations across many clips or timelines,
conforming, marker-driven assembly, and querying an edit as data. It reads a timeline as
structured information — every clip with its in/out, duration, track position and
metadata.

What it can't do is exercise visual judgement. It sees metadata, not pictures, unless you
ask it to render a still and look at one.

## Notable behaviour it works around

- **`scriptapp()` blocks forever** when Resolve is running but refuses a connection —
  inside C, without releasing the GIL, so no signal or thread timeout recovers it. Every
  connection is probed in a killable subprocess first.
- **`AddRenderJob` returns `''`, not `False`,** when it declines — so an empty job id
  would otherwise be handed back as success.
- **Resolve's dialogs are invisible to macOS Accessibility** (they're Qt-drawn), and a
  modal blocks scripting while open. Tools validate inputs client-side rather than
  provoking one.
- **Unknown render setting keys are silently ignored,** making a typo look like success.
  Keys are validated against the installed reference.

More in [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

## Development

```bash
uv run pytest                 # 195 unit tests, no Resolve needed
uv run pytest -m live         # integration suite against real Resolve
uv run ruff check . && uv run ruff format .
```

Unit tests run against an in-memory double shaped like the real API, so the suite needs no
Resolve installation and no application state to reset. The live suite works inside a
throwaway `MCP_TEST_<pid>` project and restores whatever project was open.

## Status

Verified against **DaVinci Resolve Studio 21.0.2.4** on macOS. 195 unit tests and 13 live
integration tests passing.

## Licence

MIT — see [LICENSE](LICENSE).

Not affiliated with or endorsed by Blackmagic Design. DaVinci Resolve is a trademark of
Blackmagic Design Pty Ltd.