# DaVinci Resolve MCP — Free / Community edition

Drive DaVinci Resolve from Claude Code (or any MCP client) to edit videos —
**on the free Community edition**, which blocks normal external scripting.

## Why this is different

DaVinci Resolve **Free** does not allow an external process to connect via the
scripting API (`scriptapp("Resolve")` returns `nil`); the permission toggle that
Studio exposes is absent. Verified on Resolve 21.0.0.48 across Python 3.9–3.14.

However, scripts running **inside** Resolve have full API access. So this project
uses a **bridge**:

```
Claude Code ──MCP──► server.py (this repo) ──files──► resolve_bridge.lua (inside Resolve) ──► live `resolve` object
```

- `bridge/resolve_bridge.lua` — runs inside Resolve, polls a request file,
  executes against the `resolve` object, writes a JSON response.
- `davinci_mcp/` — the external MCP server; each tool sends one RPC to the bridge.

Request/response are exchanged via files in `~/.davinci-mcp-bridge/`.

## Setup

1. **Install deps and the bridge helper:**

   ```bash
   uv sync
   python3 scripts/install_bridge.py
   ```

   The installer copies the bridge into Resolve's Scripts folder and prints the
   exact start/registration commands for your machine.

2. **Start the bridge inside Resolve** (it must be running for any tool to work):
   - **Workspace ▸ Scripts ▸ Comp ▸ MCP_Bridge** (after restarting Resolve once), or
   - **Workspace ▸ Console**, switch to **Lua**, and run
     `dofile("<repo>/bridge/resolve_bridge.lua")`.

   You should see `[bridge] UP` and `ops registered=...`. It keeps running and
   does **not** freeze the Resolve UI.

3. **Register the MCP server with Claude Code:**

   ```bash
   claude mcp add davinci-resolve -- uv run --directory <repo> davinci-resolve-mcp
   ```

   Then in Claude Code, call `bridge_status` to confirm the connection.

## Tools

`resolve_info`, `list_projects`, `current_project`, `open_project`,
`create_project`, `save_project`, `import_media`, `list_media`,
`list_timelines`, `current_timeline`, `create_timeline`,
`append_all_to_timeline`, `add_marker`, and `resolve_eval` (run arbitrary Lua —
escape hatch for anything not yet wrapped).

## Limitations (Free edition)

- Studio-only API calls return errors: transcription, subtitles-from-audio,
  AutoSync, Magic Mask, IntelliSearch, motion-deblur, speech gen, Dolby Vision.
- Render limits: 8-bit, ≤ UHD 3840×2160, ≤ 60 fps. Applying a Studio-only effect
  watermarks the export.

## Credits

Architecture and Studio-edition tool designs informed by
[samuelgursky/davinci-resolve-mcp](https://github.com/samuelgursky/davinci-resolve-mcp)
(MIT). This project is a from-scratch Free-edition rework using the bridge approach.