DaVinci Resolve MCP Server

What is DaVinci Resolve MCP Server about?

The server acts as a bridge between AI coding assistants (such as Cursor or Claude Desktop) and DaVinci Resolve. It exposes Resolve functionality through a MCP endpoint so that users can ask questions or issue commands in plain language and have Resolve react accordingly.

How to use DaVinci Resolve MCP Server?

Prerequisites – macOS or Windows with DaVinci Resolve 18.5+ installed and running, Python 3.6+ installed, optional Node.js/npm for auxiliary tools.
Installation – clone the repository, run the provided install.sh (macOS/Linux) or install.bat (Windows) which sets up a virtual environment, installs dependencies, and configures environment variables.
Configuration – add a MCP server entry to the AI assistant’s configuration file (e.g., ~/.cursor/mcp.json or %APPDATA%\Cursor\mcp.json) pointing to the Python entry script.
Launch – use the client‑specific launch scripts (scripts/mcp_resolve-cursor_start, scripts/mcp_resolve-claude_start) or the universal launcher (scripts/mcp_resolve_launcher.sh) to start the server.
Interact – within the AI assistant’s chat, issue natural‑language commands like “Create a new timeline called ‘Demo’” or “List all projects in DaVinci Resolve”.

Key Features of DaVinci Resolve MCP Server

Retrieve Resolve version and current page (Edit, Color, Fusion, etc.)
Project management: list, open, create, and save projects
Timeline operations: list timelines, create new timelines, switch timelines, add markers
Media pool actions: list clips, import media, create bins, add clips to timelines
Client‑specific launch scripts that auto‑configure environment variables and perform pre‑launch checks
Cross‑platform support for macOS and Windows (Linux not supported)
Detailed troubleshooting guidance and log files for error diagnosis

Use Cases of DaVinci Resolve MCP Server

AI‑assisted editing – ask the assistant to build a rough cut, add markers, or rename clips without manual UI interaction.
Automated project setup – generate a new project structure (bins, timelines, media imports) via a single natural‑language request.
Rapid query of project state – retrieve current timeline name, list of media assets, or Resolve version on demand.
Scripting assistance – developers can prototype Resolve scripts by describing desired actions to the AI, which then issues the corresponding commands through the server.
Education & training – newcomers can explore Resolve features by asking the assistant “How do I add a color node?” and receive an automated execution.

FAQ

Q: Do I need to run DaVinci Resolve before starting the server? A: Yes. The server checks for a running Resolve process; if it is not found, it will prompt you to start the application.

Q: Can I use this on Linux? A: Linux support is currently marked as not supported. The scripts and environment variables are tuned for macOS and Windows.

Q: Which AI assistants are supported? A: The repository provides ready‑made launch scripts and configuration templates for Cursor and Claude Desktop. Additional assistants can be added by creating a compatible MCP configuration file.

Q: Where are the logs stored? A: Logs are written to the logs/ directory and to scripts/cursor_resolve_server.log for quick diagnostics.

Q: How do I set the required environment variables manually? A: On macOS set RESOLVE_SCRIPT_API, RESOLVE_SCRIPT_LIB, and extend PYTHONPATH as shown in the README. On Windows set the analogous RESOLVE_SCRIPT_API, RESOLVE_SCRIPT_LIB, and PYTHONPATH variables.

Q: What if the server fails to connect to Resolve? A: Verify that the environment variables point to the correct Resolve scripting directories, ensure Resolve is running, and check the log files for detailed error messages.

A Model Context Protocol (MCP) server that connects AI coding assistants (Cursor, Claude Desktop) to DaVinci Resolve, enabling them to query and control DaVinci Resolve through natural language.

Features

For a comprehensive list of implemented and planned features, see docs/FEATURES.md.

Requirements

macOS or Windows with DaVinci Resolve installed
Python 3.6+
DaVinci Resolve running in the background
(Optional) Node.js/npm for some features

Installation Guide

For detailed installation instructions, please see INSTALL.md. This guide covers:

Prerequisites and system requirements
Step-by-step installation process
Configuration details
Common troubleshooting steps

Platform Support

Platform	Status	One-Step Install	Quick Start
macOS	✅ Stable	`./install.sh`	`./run-now.sh`
Windows	✅ Stable	`install.bat`	`run-now.bat`
Linux	❌ Not supported	N/A	N/A

Quick Start Guide

New One-Step Installation (Recommended)

The easiest way to get started is with our new unified installation script. This script does everything automatically:

Clone the repository:

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

Make sure DaVinci Resolve Studio is installed and running
Run the installation script: macOS/Linux:
```
./install.sh
```
Windows:
```
install.bat
```

This will:

Automatically detect the correct paths on your system
Create a Python virtual environment
Install the MCP SDK from the official repository
Set up environment variables
Configure Cursor/Claude integration
Verify the installation is correct
Optionally start the MCP server

Alternative Quick Start

You can also use the original quick start scripts:

Windows Users:

run-now.bat

macOS Users:

chmod +x run-now.sh
./run-now.sh

Configuration

For configuration of DaVinci Resolve MCP with different AI assistant clients like Cursor or Claude, see the config-templates directory.

Troubleshooting

For detailed troubleshooting guidance, refer to the INSTALL.md file which contains solutions to common issues.

Common Issues

Path Resolution

The installation scripts now use more robust path resolution, fixing issues with run-now.sh looking for files in the wrong locations
Always let the scripts determine the correct paths based on their location

DaVinci Resolve Detection

We've improved the process detection to reliably find DaVinci Resolve regardless of how it appears in the process list
Make sure DaVinci Resolve is running before starting the MCP server

Environment Variables

Make sure all required environment variables are set correctly
Review the log file at scripts/cursor_resolve_server.log for troubleshooting

Windows

Make sure to use forward slashes (/) in configuration files
Python must be installed and paths configured in configs
DaVinci Resolve must be running before starting the server

macOS

Make sure scripts have execute permissions
Check Console.app for any Python-related errors
Verify environment variables are set correctly
DaVinci Resolve must be running before starting the server

Support

For issues and feature requests, please use the GitHub issue tracker.

Launch Options

After installation, you have several ways to start the server:

Client-Specific Launch Scripts

The repository includes dedicated scripts for launching with specific clients:

# For Cursor integration (macOS)
chmod +x scripts/mcp_resolve-cursor_start
./scripts/mcp_resolve-cursor_start

# For Claude Desktop integration (macOS)
chmod +x scripts/mcp_resolve-claude_start
./scripts/mcp_resolve-claude_start

These specialized scripts:

Set up the proper environment for each client
Verify DaVinci Resolve is running
Configure client-specific settings
Start the MCP server with appropriate parameters

Pre-Launch Check

Before connecting AI assistants, verify your environment is properly configured:

# On macOS
./scripts/check-resolve-ready.sh

# On Windows
./scripts/check-resolve-ready.bat

These scripts will:

Verify DaVinci Resolve is running (and offer to start it)
Check environment variables are properly set
Ensure the Python environment is configured correctly
Validate Cursor/Claude configuration
Optionally launch Cursor

Universal Launcher

For advanced users, our unified launcher provides full control over both Cursor and Claude Desktop servers:

# Make the script executable (macOS only)
chmod +x scripts/mcp_resolve_launcher.sh

# Run in interactive mode
./scripts/mcp_resolve_launcher.sh

# Or use command line options
./scripts/mcp_resolve_launcher.sh --start-cursor    # Start Cursor server (uses mcp_resolve-cursor_start)
./scripts/mcp_resolve_launcher.sh --start-claude    # Start Claude Desktop server (uses mcp_resolve-claude_start)
./scripts/mcp_resolve_launcher.sh --start-both      # Start both servers
./scripts/mcp_resolve_launcher.sh --stop-all        # Stop all running servers
./scripts/mcp_resolve_launcher.sh --status          # Show server status

Additional options:

Force mode (skip Resolve running check): --force
Project selection: --project "Project Name"

Full Installation

For a complete manual installation:

Clone this repository:

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

Create a Python virtual environment:

# Create virtual environment
python -m venv venv

# Activate it
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies from requirements.txt
pip install -r requirements.txt

# Alternatively, install MCP SDK directly
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

Set up DaVinci Resolve scripting environment variables:

For macOS:

export RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting"
export RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so"
export PYTHONPATH="$PYTHONPATH:$RESOLVE_SCRIPT_API/Modules/"

For Windows:

set RESOLVE_SCRIPT_API=C:\ProgramData\Blackmagic Design\DaVinci Resolve\Support\Developer\Scripting
set RESOLVE_SCRIPT_LIB=C:\Program Files\Blackmagic Design\DaVinci Resolve\fusionscript.dll
set PYTHONPATH=%PYTHONPATH%;%RESOLVE_SCRIPT_API%\Modules

Alternatively, run the pre-launch check script which will set these for you:

# On macOS
./scripts/check-resolve-ready.sh

# On Windows
./scripts/check-resolve-ready.bat

Configure Cursor to use the server by creating a configuration file:

For macOS (~/.cursor/mcp.json):

{
  "mcpServers": {
    "davinci-resolve": {
      "name": "DaVinci Resolve MCP",
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "/path/to/your/davinci-resolve-mcp/src/main.py"
      ]
    }
  }
}

For Windows (%APPDATA%\Cursor\mcp.json):

{
  "mcpServers": {
    "davinci-resolve": {
      "name": "DaVinci Resolve MCP",
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\davinci-resolve-mcp\\src\\main.py"]
    }
  }
}

Start the server using one of the client-specific scripts:

# For Cursor
./scripts/mcp_resolve-cursor_start

# For Claude Desktop
./scripts/mcp_resolve-claude_start

Usage with AI Assistants

Using with Cursor

Start the Cursor server using the dedicated script:

./scripts/mcp_resolve-cursor_start

Or use the universal launcher:

./scripts/mcp_resolve_launcher.sh --start-cursor

Start Cursor and open a project.
In Cursor's AI chat, you can now interact with DaVinci Resolve. Try commands like:
- "What version of DaVinci Resolve is running?"
- "List all projects in DaVinci Resolve"
- "Create a new timeline called 'My Sequence'"
- "Add a marker at the current position"

Using with Claude Desktop

Create a claude_desktop_config.json file in your Claude Desktop configuration directory using the template in the config-templates directory.

Run the Claude Desktop server using the dedicated script:

./scripts/mcp_resolve-claude_start

Or use the universal launcher:

./scripts/mcp_resolve_launcher.sh --start-claude

In Claude Desktop, you can now interact with DaVinci Resolve using the same commands as with Cursor.

Available Features

General

Get DaVinci Resolve version
Get/switch current page (Edit, Color, Fusion, etc.)

Project Management

List available projects
Get current project name
Open project by name
Create new project
Save current project

Timeline Operations

List all timelines
Get current timeline info
Create new timeline
Switch to timeline by name
Add marker to timeline

Media Pool Operations

List media pool clips
Import media file
Create media bin
Add clip to timeline

Windows Support Notes

Windows support is stable in v1.3.3 and should not require additional troubleshooting:

Ensure DaVinci Resolve is installed in the default location
Environment variables are properly set as described above
Windows paths may require adjustment based on your installation
For issues, please check the logs in the logs/ directory

Troubleshooting

DaVinci Resolve Connection

Make sure DaVinci Resolve is running before starting the server. If the server can't connect to Resolve, check that:

Your environment variables are set correctly
You have the correct paths for your DaVinci Resolve installation
You have restarted your terminal after setting environment variables

Project Structure

davinci-resolve-mcp/
├── README.md               # This file
├── docs/                   # Documentation
│   ├── FEATURES.md         # Feature list and status
│   ├── CHANGELOG.md        # Version history
│   ├── VERSION.md          # Version information
│   ├── TOOLS_README.md     # Tools documentation
│   ├── PROJECT_MCP_SETUP.md # Project setup guide
│   └── COMMIT_MESSAGE.txt  # Latest commit information
├── config-templates/       # Configuration templates
│   ├── sample_config.json  # Example configuration
│   ├── cursor-mcp-example.json # Cursor config example
│   └── mcp-project-template.json # MCP project template
├── scripts/                # Utility scripts
│   ├── tests/              # Test scripts
│   │   ├── benchmark_server.py # Performance tests
│   │   ├── test_improvements.py # Test scripts
│   │   ├── test_custom_timeline.py # Timeline tests
│   │   ├── create_test_timeline.py # Create test timeline
│   │   ├── test-after-restart.sh # Test after restart (Unix)
│   │   └── test-after-restart.bat # Test after restart (Windows)
│   ├── batch_automation.py # Batch automation script
│   ├── restart-server.sh   # Server restart script (Unix)
│   ├── restart-server.bat  # Server restart script (Windows)
│   ├── run-now.sh          # Quick start script (Unix)
│   └── run-now.bat         # Quick start script (Windows)
├── resolve_mcp_server.py   # Main server implementation
├── src/                    # Source code
│   ├── api/                # API implementation
│   ├── features/           # Feature modules
│   └── utils/              # Utility functions
├── logs/                   # Log files
├── tools/                  # Development tools
├── assets/                 # Project assets
└── examples/               # Example code

License

MIT

Acknowledgments

Blackmagic Design for DaVinci Resolve and its API
The MCP protocol team for enabling AI assistant integration

Author

Samuel Gursky (samgursky@gmail.com)

GitHub: github.com/samuelgursky

Future Plans

Windows and Linux support
Additional DaVinci Resolve features
Support for Claude Desktop

Development

If you'd like to contribute, please check the feature checklist in the repo and pick an unimplemented feature to work on. The code is structured with clear sections for different areas of functionality.

License

MIT

Acknowledgments

Blackmagic Design for DaVinci Resolve and its API
The MCP protocol team for enabling AI assistant integration

Project Structure

After cleanup, the project has the following structure:

resolve_mcp_server.py - The main MCP server implementation
run-now.sh - Quick start script that handles setup and runs the server
setup.sh - Complete setup script for installation
check-resolve-ready.sh - Pre-launch check to verify DaVinci Resolve is ready
start-server.sh - Script to start the server
run-server.sh - Simplified script to run the server directly

Key Directories:

src/ - Source code and modules
assets/ - Project assets and resources
logs/ - Log files directory
scripts/ - Helper scripts

When developing, it's recommended to use ./run-now.sh which sets up the environment and launches the server in one step.

Changelog

See docs/CHANGELOG.md for a detailed history of changes.

Cursor-Specific Setup

When integrating with Cursor, follow these specific steps:

Make sure DaVinci Resolve is running before starting Cursor
Install required dependencies:
```
# From the davinci-resolve-mcp directory:
pip install -r requirements.txt
```
Note: This will install the MCP package and other dependencies automatically.

Set up the MCP server configuration in Cursor:

Create or edit ~/.cursor/mcp.json on macOS (or %USERPROFILE%\.cursor\mcp.json on Windows):

{
  "mcpServers": {
    "davinci-resolve": {
      "name": "DaVinci Resolve MCP",
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "/path/to/your/davinci-resolve-mcp/src/main.py"
      ]
    }
  }
}

Important Notes:

Use main.py as the entry point (not resolve_mcp_server.py)
Use absolute paths in the configuration

Common issues:
- "Client closed" error: Check that paths are correct in mcp.json and dependencies are installed
- Connection problems: Make sure DaVinci Resolve is running before starting Cursor
- Environment variables: The main.py script will handle setting environment variables

DaVinci Resolve MCP Server