Nuke-MCP

A bridge between The Foundry's Nuke and AI systems using the Model Context Protocol (MCP).

Overview

Nuke-MCP allows AI assistants to interact with Nuke through a socket connection, enabling them to:

• Get information about Nuke scripts
• Create, modify, and delete nodes
• Position nodes in the node graph
• Connect nodes together
• Control playback and rendering
• Execute arbitrary Python code in Nuke

Components

1. Nuke Addon (nuke_mcp_addon.py): A Nuke script that creates a socket server within Nuke
2. MCP Server (nuke_mcp_server.py): A Python server that connects to the Nuke addon and exposes tools to AI systems
3. Entry Point (main.py): A simple script to start the MCP server

Installation

Prerequisites

• The Foundry's Nuke (any recent version should work)
• Python 3.7+
• FastMCP package
• Claude Desktop

Installing the FastMCP package

pip install fastmcp

Installing Nuke-MCP

1. Clone or download this repository
2. Copy nuke_mcp_addon.py to your Nuke scripts folder or a location in your Nuke Python path

Usage

Installing the Nuke Addon

1. Copy the Addon File:

   • Take the nuke_mcp_addon.py file and place it in a location where Nuke can find it:
     • Copy it to your Nuke scripts folder (usually in ~/.nuke/python on Linux/Mac or in your home directory on Windows)
     • Or place it in a folder that's in your Nuke Python path

2. Create a Startup Script (Recommended):

   • Create or edit an existing init.py file in your .nuke directory
   • Add the following line to automatically load the addon when Nuke starts and making sure you're pointing to the python subfolder where the MCP tools live:

     nuke.pluginAddPath("./python")
     
     import nuke_mcp_addon
     

3. Manual Loading (Alternative):

   • If you don't want to load it automatically, you can manually load it each time by:
     • Opening Nuke
     • Make sure you have a python subfolder setup in the init.py where the MCP tools live
     • Going to the Script Editor panel
     • Running import nuke_mcp_addon

Docking the NukeMCP Panel

By default, the NukeMCP panel opens as a floating window. If you prefer to have it docked in Nuke's interface, you can modify the NukeMCPPanel class in nuke_mcp_addon.py:

# Find the NukeMCPPanel class definition (around line 380)
class NukeMCPPanel(nukescripts.PythonPanel):
    def __init__(self):
        nukescripts.PythonPanel.__init__(self, 'Nuke MCP', 'com.example.NukeMCP')
        # ... existing code ...

# Add this method to enable docking
    def addToPane(self):
        pane = nuke.getPaneFor('Properties.1')
        if not pane:
            pane = nuke.getPaneFor('Viewer.1')
        self.setMinimumSize(300, 200)  # Set a reasonable minimum size
        return pane.addPermanentAsQWidget(self)

# Modify the show_panel function to use docking
def show_panel():
    """Show the NukeMCP panel"""
    global _panel
    if _panel is None:
        _panel = NukeMCPPanel()
    
    # Show as docked panel instead of floating window
    pane = _panel.addToPane()
    if pane:
        _panel.setParent(pane)

You can also modify how the panel appears in the menu. Based on your menu.py file, you have:

# MCP Tools
nuke.toolbar("Nodes").addCommand('NukeMCP/NukeMCP Panel', 'nuke_mcp_addon.show_panel()')

To ensure it's properly integrated with your existing toolbar structure, make sure this line is uncommented in your menu.py file.

Troubleshooting

To use Nuke-MCP with Claude Desktop, follow these steps:

1. Download and Install Claude Desktop:

   • Download Claude Desktop from Anthropic's website
   • Install and set up your account

2. Enable Developer Mode:

   • Open Claude Desktop
   • Go to Settings
   • Enable Developer Mode (this might require specific permissions)

3. Edit the Configuration File:

   • In Claude Desktop settings, click "Edit Config" (or directly edit the claude_desktop_config.json file)
   • Add the Nuke-MCP server configuration:

{
  "mcpServers": {
    "nuke": {
      "command": "python",
      "args": [
        "/path/to/your/nuke-mcp/main.py"
      ],
      "trusted": true
    }
  }
}

1. Replace the Path:

   • Update the path with the actual path to where you saved the main.py file
   • Make sure to use the full absolute path
   • For Windows, use either forward slashes or escaped backslashes:

     "args": ["Z:/path/to/nuke_mcp/main.py"]
     

     or

     "args": ["Z:\\path\\to\\nuke_mcp\\main.py"]
     

   • Note: The "trusted": true flag is required for full functionality

2. Restart Claude Desktop:

   • Save the configuration file
   • Restart Claude Desktop to apply the changes

Now when you use Claude Desktop, you can instruct it to interact with Nuke through the MCP connection.

System Architecture

The system consists of three main components that work together:

1. Nuke Addon: Runs inside Nuke and creates a socket server that listens for commands
2. MCP Server: Acts as middleware between AI systems and Nuke
3. AI Client: Connects to the MCP Server to control Nuke (e.g., Claude Desktop)

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│             │     │             │     │             │
│  AI Client  │◄───►│  MCP Server │◄───►│  Nuke Addon │
│ (Claude)    │     │             │     │ (in Nuke)   │
│             │     │             │     │             │
└─────────────┘     └─────────────┘     └─────────────┘

Available Tools

The MCP server exposes the following tools:

• get_script_info(): Get information about the current Nuke script
• get_node_info(node_name): Get details about a specific node
• create_node(node_type, name, position, inputs, parameters): Create a new node
• modify_node(name, parameters, position, inputs): Change an existing node
• delete_node(name): Delete a node
• position_node(name, x, y): Position a node in the node graph
• connect_nodes(output_node, input_node, input_index): Connect nodes
• render(frame_range, write_node, proxy_mode): Render frames
• viewer_playback(action, start_frame, end_frame): Control Viewer playback
• execute_nuke_code(code): Run Python code in Nuke
• auto_layout_nodes(selected_only): Automatically arrange nodes
• set_frames(first_frame, last_frame, current_frame): Set frame range
• create_viewer(input_node): Create a Viewer node

Examples

Creating a Simple Blur Node

create_node(node_type="Blur", parameters={"size": 10})

Building a Grade Node Chain

create_node(node_type="Read", name="input", parameters={"file": "/path/to/image.exr"})
create_node(node_type="Grade", name="grade1", position=[200, 0])
create_node(node_type="Grade", name="grade2", position=[400, 0])
create_node(node_type="Write", name="output", position=[600, 0], parameters={"file": "/path/to/output.exr"})
connect_nodes(output_node="input", input_node="grade1")
connect_nodes(output_node="grade1", input_node="grade2")
connect_nodes(output_node="grade2", input_node="output")

Rendering Output

render(frame_range="1-10", write_node="output")

Example Commands for Claude

When working with Claude Desktop, you can give it natural language instructions to control Nuke. Here are some example commands:

Basic Script Analysis

"Can you tell me what's in my current Nuke script?"

Creating a Complete Compositing Setup

"Create a compositing setup in Nuke with a Read node, Color Correct, Grade, and Write node, all properly connected."

Building a Green Screen Keying Setup

"Create a professional green screen keying setup in Nuke with Keyer, Despill, Edge Blur, and compositing over a background."

Adding Special Effects

"Build a particle system in Nuke using Noise, ParticleEmitter, and Merge nodes to create a fire effect."

Enhancing an Existing Script

"Analyze my current Nuke script, then enhance it by creating a color grading chain with separate adjustments for shadows, midtones, and highlights. Add a subtle film grain effect and a gentle vignette."

3D Scene Setup

"Set up a 3D scene in Nuke with a Camera, 3D objects, and proper lighting."

Extending the MCP Tools

You can extend the system by adding new tools to the nuke_mcp_server.py file. The MCP tools are defined using the @mcp.tool() decorator pattern.

Tool Structure

Each tool follows this basic structure:

@mcp.tool()
def tool_name(ctx: Context, param1: type, param2: type = default_value) -> str:
    """
    Tool description for documentation.
    
    Parameters:
    - param1: Description of param1
    - param2: Description of param2 with default value
    """
    try:
        logger.info(f"Tool called: tool_name with params")
        nuke = get_nuke_connection()
        result = nuke.send_command("command_name", {
            "param1": param1,
            "param2": param2
        })
        
        # Process result and format response
        return "Human-readable response"
    except Exception as e:
        logger.error(f"Error in tool_name: {str(e)}")
        return f"Error message: {str(e)}"

Adding a New Tool

To add a new tool:

1. Identify the functionality you want to add

2. Add a new method in the Nuke addon (in nuke_mcp_addon.py):

   • Add the method to the NukeMCPServer class
   • Add an entry to the handlers dictionary in the execute_command method

3. Create a corresponding tool in nuke_mcp_server.py:

   • Use the @mcp.tool() decorator
   • Define parameters with type hints
   • Add a descriptive docstring
   • Implement the logic to call the corresponding Nuke command

4. Test the new tool thoroughly

Example: Adding a Transform Node Tool

Here's an example of how you might add a specialized tool for creating a Transform node:

@mcp.tool()
def create_transform(
    ctx: Context,
    name: str = None,
    position: List[int] = None,
    rotation: float = 0.0,
    scale: float = 1.0,
    center: List[float] = None
) -> str:
    """
    Create a Transform node with specified parameters.
    
    Parameters:
    - name: Optional name for the Transform node
    - position: Optional [x, y] position coordinates for the node
    - rotation: Rotation in degrees
    - scale: Uniform scale factor
    - center: Optional [x, y] center of transformation
    """
    try:
        logger.info(f"Tool called: create_transform")
        nuke = get_nuke_connection()
        
        # Prepare parameters for the Transform node
        parameters = {
            "rotate": rotation,
            "scale": scale
        }
        
        if center:
            parameters["center"] = center
        
        # Call the generic create_node command
        result = nuke.send_command("create_node", {
            "node_type": "Transform",
            "name": name,
            "position": position,
            "parameters": parameters
        })
        
        actual_name = result.get("name", "unknown")
        return f"Created Transform node named '{actual_name}' with rotation={rotation}° and scale={scale}"
    except Exception as e:
        logger.error(f"Error in create_transform: {str(e)}")
        return f"Error creating Transform node: {str(e)}"

This pattern allows you to build specialized tools that provide higher-level functionality while leveraging the existing command infrastructure.

Troubleshooting

Connection Issues

If Claude cannot connect to Nuke, check the following:

1. Nuke is Running: Make sure Nuke is open and running
2. Addon is Active: Verify the NukeMCP panel shows "Running on port 9876"
3. Port Configuration: Ensure the port matches in both Nuke and the MCP server
4. Firewall Settings: Check if your firewall is blocking the connection

Common Errors

• "Could not connect to Nuke": Make sure the Nuke addon is running and using the correct port
• "Socket timeout while waiting for response": The operation in Nuke may be taking too long
• "Failed to create node": Check if the node type name is correct

Development

This is an initial implementation. Future improvements could include:

• Support for more specialized Nuke functionality (Roto, Tracking, etc.)
• Better error handling and timeout management
• Support for template-based workflows
• Integration with additional asset management systems

License

MIT License