iflow-mcp_dughogan-nuke_mcp 0.1.0
A bridge between The Foundry's Nuke and AI systems using the Model Context Protocol (MCP)
Requires Python: >=3.7

# 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

```bash
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:
     ```python
     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`:

```python
# 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:

```python
# 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:

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

4. **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

5. **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:

```python
@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:

```python
@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](LICENSE)