DaVinci Resolve & AI: Unleashing Creative Power with the Model Context Protocol

Elevate Your Editing Workflow with Seamless AI Integration

This document details the DaVinci Resolve Model Context Protocol (MCP) server, a powerful tool that bridges the gap between cutting-edge AI coding assistants (like Cursor and Claude Desktop) and the industry-leading DaVinci Resolve software. By leveraging the open Model Context Protocol, this server empowers you to control and query DaVinci Resolve using natural language, revolutionizing your post-production workflow.

Core Capabilities: AI-Assisted Editing at Your Fingertips

This MCP server acts as a translator, enabling AI assistants to understand and execute your commands within DaVinci Resolve. Imagine instructing your AI to "Create a new timeline called 'My Sequence'" or "Add a marker at the current position" – this server makes it a reality.

Key Features:

• Natural Language Control: Interact with DaVinci Resolve using intuitive, human-readable commands.
• Seamless Integration: Connects DaVinci Resolve with popular AI coding assistants like Cursor and Claude Desktop.
• Extensible Architecture: Built upon the open Model Context Protocol for future compatibility and feature expansion.
• Cross-Platform Support: Stable and reliable performance on both macOS and Windows.

For a comprehensive breakdown of implemented and planned features, consult the detailed Feature Roadmap.

System Requirements: Ensuring a Smooth Experience

To harness the power of this MCP server, ensure your system meets the following prerequisites:

• Operating System: macOS or Windows
• Software: DaVinci Resolve (version 18.5 or later) installed and running in the background.
• Programming Language: Python 3.6+
• (Optional): Node.js/npm (required for certain advanced features)

Installation: A Streamlined Setup Process

We've simplified the installation process to get you up and running quickly. For detailed, step-by-step instructions, refer to the comprehensive Installation Guide. This guide covers:

• Detailed prerequisites and system compatibility checks.
• A clear, step-by-step installation procedure.
• Essential configuration details for optimal performance.
• Troubleshooting tips and solutions to common issues.

Platform Compatibility: Ready for Your Environment

Quick Start: Jumpstart Your AI-Powered Workflow

The recommended approach is the one-step installation script, automating the entire setup process:

1. Clone the Repository:

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

2. Ensure DaVinci Resolve is Running: Verify that DaVinci Resolve Studio is installed and actively running in the background.

3. Execute the Installation Script:

   • macOS/Linux:

     ./install.sh

   • Windows:

     install.bat

This script intelligently automates the following tasks:

1. Path Detection: Automatically identifies the correct file paths on your system.
2. Virtual Environment Creation: Establishes a dedicated Python virtual environment for the server.
3. MCP SDK Installation: Installs the official MCP SDK from the designated repository.
4. Environment Variable Configuration: Configures essential environment variables for seamless operation.
5. AI Assistant Integration: Sets up integration with Cursor and Claude Desktop.
6. Installation Verification: Confirms the installation's integrity.
7. (Optional) Server Startup: Provides the option to immediately launch the MCP server.

Alternative Quick Start (Legacy)

Alternatively, you can utilize the original quick start scripts:

Windows Users:

run-now.bat

macOS Users:

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

Configuration: Tailoring the Server to Your Needs

Customize the DaVinci Resolve MCP server for optimal integration with your preferred AI assistant client (Cursor or Claude) using the configuration templates located in the config-templates directory.

Troubleshooting: Resolving Common Issues

The Installation Guide provides comprehensive troubleshooting guidance and solutions to frequently encountered problems.

Key Troubleshooting Areas:

• Path Resolution: The installation scripts now feature enhanced path resolution, addressing previous issues with incorrect file location lookups. Always allow the scripts to automatically determine the correct paths based on their location.
• DaVinci Resolve Detection: Improved process detection ensures reliable identification of DaVinci Resolve, regardless of its appearance in the process list. Ensure DaVinci Resolve is running before initiating the MCP server.
• Environment Variables: Verify that all required environment variables are correctly configured. Review the log file at scripts/cursor_resolve_server.log for detailed troubleshooting information.

Platform-Specific Considerations:

• Windows: Utilize forward slashes (/) in configuration files. Ensure Python is installed and its paths are correctly configured. DaVinci Resolve must be running before starting the server.
• macOS: Verify that scripts have execute permissions. Check Console.app for Python-related errors. Confirm that environment variables are correctly set. DaVinci Resolve must be running before starting the server.

Support: Getting the Help You Need

For bug reports, feature requests, and general assistance, please utilize the GitHub issue tracker.

Launch Options: Flexible Server Startup

After installation, you have multiple options for launching the server:

Client-Specific Launch Scripts

Dedicated scripts are provided for launching the server with specific AI assistants:

# 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 scripts streamline the launch process by:

• Configuring the environment for each client.
• Verifying that DaVinci Resolve is running.
• Configuring client-specific settings.
• Starting the MCP server with the appropriate parameters.

Pre-Launch Check: Ensuring a Ready Environment

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

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

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

These scripts perform the following checks:

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

Universal Launcher: Advanced Control

For advanced users, the unified launcher provides comprehensive 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 (Manual)

For a complete manual installation, follow these steps:

1. Clone the Repository:

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

2. 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

3. 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

4. Configure Cursor (if applicable):

   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"]
       }
     }
   }

5. Start the Server:

   # For Cursor
   ./scripts/mcp_resolve-cursor_start
   
   # For Claude Desktop
   ./scripts/mcp_resolve-claude_start

Usage with AI Assistants: Unleash the Potential

Cursor Integration

1. Start the Cursor Server:

   ./scripts/mcp_resolve-cursor_start

   Or use the universal launcher:

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

2. Launch Cursor: Start Cursor and open a project.

3. Interact with DaVinci Resolve: In Cursor's AI chat, use 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"

Claude Desktop Integration

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

2. Start the Claude Desktop Server:

   ./scripts/mcp_resolve-claude_start

   Or use the universal launcher:

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

3. Interact with DaVinci Resolve: In Claude Desktop, use the same commands as with Cursor.

Available Features: A Growing Ecosystem

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: Stable and Reliable

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, check the logs in the logs/ directory.

Troubleshooting: Resolving Connection Issues

If the server can't connect to Resolve, check that:

1. DaVinci Resolve is running before starting the server.
2. Your environment variables are set correctly.
3. You have the correct paths for your DaVinci Resolve installation.
4. You have restarted your terminal after setting environment variables.

Project Structure: Navigating the Codebase

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

Acknowledgments

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

Author

Samuel Gursky ([email protected])

• GitHub: github.com/samuelgursky

Future Plans

• Linux support
• Additional DaVinci Resolve features
• Enhanced Claude Desktop support

Development: Contributing to the Future

We encourage contributions! Check the feature checklist in the repository and select an unimplemented feature to work on. The code is structured with clear sections for different areas of functionality.

Project Structure (Simplified)

• 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.

During development, use ./run-now.sh to set up the environment and launch the server in one step.

Changelog: Tracking Progress

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

Cursor-Specific Setup: Fine-Tuning the Integration

When integrating with Cursor, follow these specific steps:

1. Ensure DaVinci Resolve is Running: DaVinci Resolve must be running before starting Cursor.

2. Install Dependencies:

   # From the davinci-resolve-mcp directory:
   pip install -r requirements.txt

   This will install the MCP package and other dependencies automatically.

3. Configure MCP Server 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.

4. Troubleshooting:

   • "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.