davinci-resolve-ai-bridge

# Start Here: Open `00_START_HERE.html` **For the clearest setup, open [`00_START_HERE.html`](./00_START_HERE.html) first.** It is the visual, step-by-step guide for macOS, Windows, Antigravity, Claude Code, Codex, Cursor, and Remotion. Keep this entire folder together while using it. # Resolve AI Bridge Resolve AI Bridge is an MIT-licensed local MCP bridge that lets a compatible AI client inspect and control the project currently open in DaVinci Resolve. The design is intentionally small: 1. `ResolveConsole.py` starts inside Resolve's Python 3 Console and captures the internal Resolve API object. 2. A daemon thread reads authenticated JSON jobs from `~/.resolve-ai-bridge/inbox` while the Console remains available. 3. `bridge/server.py` exposes a focused set of MCP tools to your AI client over stdio. 4. Replies return through `~/.resolve-ai-bridge/outbox`. There is no hosted bridge account and no network listener. Your AI provider may still process prompts according to its own privacy policy. ## Requirements - DaVinci Resolve with the internal Python 3 Console available - Python 3.10 or newer on the computer - An MCP-compatible client such as Antigravity, Claude Code, Codex, or Cursor - Internet access during installation so pip can install the Python MCP package - Node.js current LTS, heavily recommended for Remotion motion graphics The bridge itself does not require Node.js. Node.js is for the recommended Remotion workflow. ## Quick Setup ### 1. Download the complete repository On GitHub select **Code**, then **Download ZIP**, and extract it. Do not copy only `install.py`; it needs the `agent`, `bridge`, and `skills` folders beside it. You may rename the downloaded repository folder. The installer copies runtime files to a fixed location so later repository renames do not break the Console line. ### 2. Run the installer macOS: ```bash python3 install.py ``` Windows PowerShell: ```powershell py install.py ``` The installer: - Copies the runtime to `~/.resolve-ai-bridge` - Preserves or creates a private `rab_...` token - Creates `~/.resolve-ai-bridge/.venv` - Installs the official Python MCP dependency into that venv - Writes filled MCP JSON plus exact Console, Claude Code, and Codex command files - Installs the included Resolve editing skill for Claude Code and Codex skill locations It does not rewrite an AI client's existing MCP settings. ### 3. Start the agent inside Resolve 1. Open Resolve and the project you want to edit. 2. Open **Workspace > Console**. 3. Select **Py3**. 4. Paste the exact line printed by the installer. macOS shape: ```python exec(open("/Users/YOUR_NAME/.resolve-ai-bridge/ResolveConsole.py", encoding="utf-8").read()) ``` Windows shape: ```python exec(open(r"C:\Users\YOUR_NAME\.resolve-ai-bridge\ResolveConsole.py", encoding="utf-8").read()) ``` The original installed filename is **`ResolveConsole.py`**. Do not rename that installed file. If it was moved or renamed, run the installer again and use its newly printed line. The Console should immediately print: - `RESOLVE AI BRIDGE READY` - The local token - A single-server MCP object - A full `mcpServers` JSON block The worker is a daemon thread, so the pasted line returns and releases the Console immediately. To stop it in the same Resolve session: ```python __resolve_ai_bridge_runtime__.stop() ``` ### 4. Add the MCP server to your AI client Use the filled JSON printed by Resolve or open: ```text ~/.resolve-ai-bridge/mcp-config.json ``` Its shape is: ```json { "mcpServers": { "resolve-ai-bridge": { "command": "/ABSOLUTE/PATH/TO/.resolve-ai-bridge/.venv/bin/python", "args": [ "/ABSOLUTE/PATH/TO/.resolve-ai-bridge/bridge/server.py" ], "env": { "RESOLVE_AI_BRIDGE_TOKEN": "RAB_TOKEN_PRINTED_IN_RESOLVE" } } } } ``` Do not use `~` or a relative path in MCP settings. Use the absolute paths generated by the installer. #### Antigravity 1. Open the Agent panel. 2. Open the three-dot menu and select **MCP Servers**. 3. Choose **Manage MCP Servers**, then **View raw config**. 4. Merge the `resolve-ai-bridge` entry into the existing `mcpServers` object. 5. Preserve every server already in the file. 6. Save, refresh the MCP list, and restart Antigravity if needed. Opening raw config through the application avoids guessing which config path a particular Antigravity version uses. #### Claude Code The installer and Resolve Console print an exact command that safely reads the generated JSON file. Run that printed command in a normal terminal. It has this macOS shape: ```bash claude mcp add-json resolve-ai-bridge "$(cat ~/.resolve-ai-bridge/claude-server-entry.json)" --scope user ``` On Windows, use the PowerShell command printed by the installer. The exact command is also saved at `~/.resolve-ai-bridge/claude-command.txt`. Restart Claude Code and run `/mcp`. If your installed version does not support `add-json`, merge the full JSON through its MCP settings instead. #### Codex The Resolve Console and installer both print an exact command for your installed paths and token. It has this shape: ```bash codex mcp add resolve-ai-bridge --env RESOLVE_AI_BRIDGE_TOKEN=TOKEN -- /absolute/path/to/.venv/python /absolute/path/to/bridge/server.py ``` Run the filled command in a normal terminal, then use `codex mcp list`. The same filled line is saved at `~/.resolve-ai-bridge/codex-command.txt`. The Codex app and CLI also let you add a local STDIO server through **Settings > MCP servers**. #### Cursor Open **Cursor Settings**, search for **MCP**, choose **Add new global MCP server**, and merge the generated entry into `mcpServers`. Save and enable it. ### 5. Verify before editing Keep the Console agent running, then run: ```bash python3 tools/doctor.py ``` On Windows: ```powershell py tools/doctor.py ``` Then ask your AI: ```text Call resolve_status and tell me the open project and timeline. Do not edit anything. ``` For a safe first write: ```text Inspect the timeline. Add a blue marker at the current playhead named Bridge test, then inspect again to verify it. ``` ## Token Behavior The token is functional, not decorative. - The installer writes it to `~/.resolve-ai-bridge/token.txt` with restricted permissions where supported. - The MCP process receives the same token through its environment. - Every job includes the token. - The agent compares it before executing an operation. - A mismatched request is rejected. The token protects this local queue from accidental or unrelated local requests. It is not an internet login. Do not commit it, post it, or paste it into a public issue. Rotate it if exposed: ```bash python3 install.py --rotate-token ``` Then restart the Resolve agent and replace the old MCP entry in your AI client. ## MCP Tools The server intentionally exposes fewer than 20 focused tools so a model can choose them reliably. | Tool | Purpose | | --- | --- | | `resolve_status` | Check agent, Resolve, project, timeline, and token id | | `project_info` | Read project frame rate and resolution | | `list_timelines` | List all timelines | | `open_timeline` | Select a timeline by name or index | | `timeline_overview` | Inspect tracks, markers, clips, and stable ids | | `list_media` | Walk Media Pool bins | | `import_media` | Import absolute local file paths | | `append_media` | Append media ids or imported paths | | `create_timeline` | Create an empty timeline | | `set_playhead` | Move to a timecode | | `add_marker` | Add a timeline marker | | `delete_marker` | Delete a marker at a relative frame | | `set_clip_property` | Change a supported timeline item property | | `set_clip_enabled` | Enable or disable one item | | `set_clip_color` | Set or clear a Resolve clip color | | `delete_clips` | Delete selected items after approval | | `save_project` | Save the open project | | `render_current_timeline` | Queue or start a render after approval | The MCP server also provides `resolve://guide` and an `edit_video` prompt. ## Getting Better AI Edits The included `resolve-ai-editing` skill uses an inspect, plan, edit, verify workflow. The installer copies it to Claude Code and Codex skill folders and keeps a reference copy at: ```text ~/.resolve-ai-bridge/skills/resolve-ai-editing/SKILL.md ``` Start complicated requests with: ```text First inspect the open project and timeline. Summarize what is there, state a short edit plan, and list assumptions. Work in small steps and verify after each change. Ask before deleting clips or starting a render. ``` Good prompts include: - Target platform and aspect ratio - Desired duration - Audience and story goal - Reference style - What must not change - Whether deletion and rendering are allowed Skills improve API usage and planning. They do not make subjective editing quality automatic. Review the timeline and use project backups. ## Remotion Setup, Heavily Recommended [Remotion](https://www.remotion.dev/) creates video with React. It is useful for motion graphics, animated type, explainers, and designed scenes that are awkward through Resolve's scripting API. Remotion does not control Resolve and is not installed inside the Python bridge. The practical workflow is: 1. Build and preview a designed clip with a coding agent and Remotion. 2. Render the clip to a local media file. 3. Import that file through Resolve AI Bridge. 4. Ask where it should be placed before appending it. ### Install Node.js Install the current LTS release from [nodejs.org](https://nodejs.org/). Open a new normal terminal and verify: ```bash node --version npm --version ``` ### Install the official Remotion skill and create a project Run in a normal terminal, not the Resolve Console: ```bash npx -y skills@latest add remotion-dev/skills -g -y npx create-video@latest --yes --blank my-video cd my-video npm install npx remotion skills add npm run dev ``` The maintained `remotion-dev/skills` bundle teaches supported coding agents Remotion composition, timing, media, and animation practices. Open your AI client in the `my-video` folder. Example prompt: ```text Use the official Remotion skill. Before coding, propose a 15-second 1920x1080 motion graphic with three scenes. Use my exact copy, restrained typography, and smooth transitions. Keep important content inside safe margins. Build it, run checks, and open Remotion Studio so I can review it before rendering. ``` Render the approved composition: ```bash npx remotion render <CompositionId> out/video.mp4 ``` Then give the absolute output path to your Resolve AI: ```text Import /absolute/path/to/my-video/out/video.mp4. Inspect the current timeline and ask me where to place it before appending it. ``` See `docs/REMOTION.md` for a detailed workflow and prompt checklist. ## Architecture ```text AI client | MCP over stdio v ~/.resolve-ai-bridge/bridge/server.py | authenticated JSON files v ~/.resolve-ai-bridge/inbox and outbox | v ResolveConsole.py daemon thread inside Resolve | v Current Resolve project and timeline ``` ## Known Boundaries - Resolve's public scripting API does not expose every action from the Edit page. - Transition creation and arbitrary timeline repositioning are not offered because they cannot be implemented reliably with the documented API surface. - Background-thread access to Resolve's internal objects can vary by Resolve build. The Console returns immediately by design, but real compatibility must be verified on your exact version. - Render presets must already exist in Resolve. - Complex Fusion automation is intentionally not included in this first simple version. Use Remotion for designed motion, or add Fusion operations only after testing them on real projects. - The bridge works on the currently open local project. It is not a remote collaboration server. ## Verification Status - The React instructions application is built with Vite as part of repository verification. - `tools/doctor.py` compiles every Python source in memory before checking the installation. - A real Resolve session is still required to verify the injected API object and each editing operation on a specific Resolve build. Do not interpret a successful web build as proof that a particular Resolve API operation works on every Resolve version. ## Repository Layout ```text 00_START_HERE.html visual setup guide README.md complete written reference install.py cross-platform installer install-macos.command macOS double-click wrapper install-windows.bat Windows double-click wrapper requirements.txt Python MCP dependency agent/ResolveConsole.py internal Resolve Console agent bridge/client.py authenticated file queue bridge/server.py MCP tools over stdio tools/doctor.py syntax, install, heartbeat, and round-trip checks skills/resolve-ai-editing/ included Agent Skill docs/ troubleshooting, recipes, and Remotion guide src/ source for the visual guide ``` ## Development Web guide: ```bash npm install npm run dev npm run build ``` Python syntax and local installation checks: ```bash python3 tools/doctor.py ``` Important contributor rules are in `AGENTS.md`. ## Need Help From Your Provider? After following the steps above, paste this into Antigravity, Claude Code, Codex, or another local coding agent: ```text Read 00_START_HERE.html and README.md in this project. Run tools/doctor.py, inspect ~/.resolve-ai-bridge/mcp-config.json, and configure your own MCP settings for resolve-ai-bridge. Preserve my existing MCP servers. Do not change or expose the token. Test with resolve_status only and explain any error in simple steps. ``` ## License MIT. See [`LICENSE`](./LICENSE).