nuke-mcp

nuke-mcp

     

Production-grade MCP server for Foundry Nuke. Built for compositors who want an AI assistant that actually understands their comp -- AOVs, deep, distortion, tracking, OCIO/ACEScct, CopyCat ML -- not just create_node.

90-second demo

Voice prompt -> AOV merge built -> deep holdout chain wired -> ZDefocus rendered -> all visible in Nuke DAG.


Demo script + screenplay: DEMO.md.

What it does

• Reads your comp natively. Claude sees every node, connection, and non-default knob value. No screenshots, no copy-paste.
• Builds comp-domain primitives, not just nodes. AOV reconstruction, deep holdout chains, lens-distortion envelopes, planar / 3D camera track patches, ACEScct audits, CopyCat training -- one tool call each.
• Runs long jobs as MCP Tasks. Render frames, train CopyCat, bake SmartVector. Cancellable. Survives reconnect. State on disk.
• Studio-friendly destructive gates. AST-level safety scanner blocks nuke.scriptClose, os.remove, write-mode open() and friends inside execute_python. Audit log never auto-fixes.
• Salt Spill domain depth. First DCC MCP with a comp-domain macro library: setup_karma_aov_pipeline, setup_flip_blood_comp, setup_spaceship_track_patch, audit_acescct_consistency.

Why nuke-mcp

| | nuke-mcp | Foundry + Griptape | kleer001/nuke-mcp | |---|---|---|---| | Comp-domain macros (AOV / Deep / Distortion / Tracking) | yes | no published roadmap | no | | MCP 2025-11-25 Tasks primitive | yes (first DCC MCP) | no | no | | Pydantic structured outputs | yes | n/a | no | | OCIO / ACEScct audit | yes | no | no | | CopyCat ML training as Task | yes | no | no | | Skill profiles (paginated tool surface) | yes (10 profiles) | n/a | no | | AST safety scanner on execute_python | yes | n/a | no | | Audit log + destructive gates | yes | n/a | no | | Tool count | 86 | n/a | 40+ | | Adoption posture | depth-not-breadth, comp-first | orchestration play | breadth, low adoption |

Foundry + Griptape (Feb 2026 acquisition) is an orchestration play. No published Nuke MCP roadmap. nuke-mcp differentiates on depth: comp-domain macros that ship working topology, not just node primitives.

kleer001/nuke-mcp has 40+ atomic tools but no comp-domain macros, no Tasks primitive, no OCIO audit, no Pydantic outputs. nuke-mcp is the first DCC MCP to ship the MCP 2025-11-25 Tasks primitive (unclaimed flag claimed here).

Feature matrix

| Capability | What you get | Profile | |---|---|---| | Tools | 86 across 10 profiles, surfaced lazily via load_profile | (all) | | Tasks primitive | Disk-persisted state machine: working / input_required / completed / failed / cancelled. Survives reconnect. | core | | Skill profiles | Paginated tool surface. Default = core (~45 tools). load_profile("tracking") to expand. | core | | Pydantic outputs | NodeDetail, Comp, RenderResult, KnobValue, DiffResult | (cross-cutting) | | OCIO / ACEScct | get_color_management, set_working_space, audit_acescct_consistency, convert_node_colorspace, create_ocio_colorspace | color | | AOV pipeline | detect_aov_layers, setup_karma_aov_pipeline (per-layer Shuffle + reconstruction Merge + QC viewer-pair), setup_aov_merge | aov | | Deep workflow | create_deep_recolor / merge / holdout / transform, deep_to_image, setup_flip_blood_comp (FLIP -> ZDefocus chain) | deep | | Distortion / STMap | bake_lens_distortion_envelope, apply_idistort, apply_smartvector_propagate, generate_stmap | distortion | | Tracking | setup_camera_tracker, setup_planar_tracker, setup_tracker4, bake_tracker_to_corner_pin, solve_3d_camera, bake_camera_to_card, setup_spaceship_track_patch | tracking | | CopyCat ML | train_copycat, serve_copycat, setup_dehaze_copycat, list_cattery_models, install_cattery_model | copycat | | Audit | audit_acescct_consistency, audit_write_paths, audit_naming_convention, audit_render_settings, qc_viewer_pair | audit | | Workflow prompts | 8 first-class MCP prompts: AOV relight, deep holdout, SmartVector paint propagate, CopyCat dehaze, STMap envelope, planar / 3D camera track, ACEScct audit | (prompts/) |

Requirements

• Python 3.10+
• Foundry Nuke 15.x or 16.x
• An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

Quick start

git clone https://github.com/cian-bit/nuke-mcp.git
cd nuke-mcp
python -m venv .venv
.venv/Scripts/pip install -e .       # Windows
# .venv/bin/pip install -e .         # macOS/Linux

Nuke addon setup

Copy the nuke_plugin/ contents to ~/.nuke/nuke_mcp_addon/:

~/.nuke/
  nuke_mcp_addon/
    __init__.py
    addon.py
    menu.py

Add to ~/.nuke/init.py:

nuke.pluginAddPath('./nuke_mcp_addon')

Add to ~/.nuke/menu.py:

import nuke_mcp_addon
toolbar = nuke.menu("Nodes")
mcp_menu = toolbar.addMenu("MCP")
mcp_menu.addCommand("Start Server", nuke_mcp_addon.start)
mcp_menu.addCommand("Stop Server", nuke_mcp_addon.stop)

Claude Desktop config (minimal)

claude_desktop_config.json:

{
  "mcpServers": {
    "nuke": {
      "command": "C:\\path\\to\\nuke-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "nuke_mcp"],
      "env": {
        "NUKE_HOST": "localhost",
        "NUKE_PORT": "9876"
      }
    }
  }
}

Claude Code config

~/.claude/mcp.json:

{
  "nuke": {
    "command": "nuke-mcp"
  }
}

Usage

1. Open Nuke.
2. Start the MCP addon: Nodes > MCP > Start Server.
3. Open Claude. Start talking to your comp.

The default profile is core (~45 tools). Specialised surfaces are opt-in:

list_profiles()                    # see what's available
load_profile("tracking")           # surface camera / planar tracker tools
load_profile("deep")               # surface DeepRecolor / DeepHoldout / setup_flip_blood_comp
load_profile("aov")                # surface Karma AOV pipeline
load_profile("audit")              # surface ACEScct / write-path / naming audits

Tool surface

96 tools across 10 profiles. Open src/nuke_mcp/profiles.py for the full mapping.

| Profile | Tools | What's in it | |---|---|---| | core | 45 | Reads, graph mutations, knobs, expressions, keyframes, render, script, roto, viewer, scene digest, profile loader, Tasks meta | | graph_advanced | 4 | create_nodes, set_knobs, execute_python, read_selected | | color | 7 | Keying, colour-correction, OCIO/ACEScct primitives | | aov | 3 | detect_aov_layers, setup_karma_aov_pipeline, setup_aov_merge | | tracking | 7 | 2D + 3D tracking primitives + setup_spaceship_track_patch macro | | deep | 6 | Deep primitives + setup_flip_blood_comp macro | | distortion | 4 | Lens distortion envelope, STMap, IDistort, SmartVector propagate | | copycat | 5 | CopyCat training (Task), inference, dehaze macro, Cattery registry | | audit | 5 | ACEScct, write paths, naming, render settings, QC viewer pair |

MCP Tasks primitive

nuke-mcp is the first DCC MCP to ship the MCP 2025-11-25 Tasks primitive. Long-running operations (render_frames, train_copycat, bake_smartvector, solve_3d_camera, etc.) return a task_id and stream task_progress notifications. State is persisted to ~/.nuke_mcp/tasks/<id>.json. Survives MCP reconnect, Nuke restart, and client crash.

render_frames(write_node="Write1", first=1001, last=1240) -> {task_id: "abc123..."}
tasks_get("abc123...")  # -> {state: "working", progress: {frame: 1156, total: 240, ...}}
tasks_cancel("abc123...")  # graceful stop at next frame boundary
tasks_resume("abc123...")  # if MCP died mid-render

Architecture

Claude / Cursor / etc
    | stdio (MCP protocol)
    v
nuke-mcp server (Python subprocess)
    | TCP socket (JSON, port 9876)
    | request_id echo, heartbeat, SO_KEEPALIVE
    v
Nuke addon (threaded server inside Nuke)
    | nuke.executeInMainThreadWithResult()
    v
Nuke Python API

Safety

execute_python runs through an AST + regex scanner that blocks:

• nuke.scriptClose, nuke.scriptClear, nuke.scriptExit, nuke.exit, nuke.delete, nuke.removeAllKnobChanged
• os.remove, os.unlink, shutil.rmtree, os.system
• subprocess.Popen / run / call
• Write-mode open() (AST-detected, not regex-fragile)
• Indirection: getattr, __import__, import as aliases, eval, exec, walrus, globals / vars / sys.modules, unicode homoglyphs

Audit tools (audit_acescct_consistency, audit_write_paths, audit_naming_convention, audit_render_settings) are read-only. Never auto-fix.

Workflow prompts

8 first-class MCP prompts under src/nuke_mcp/prompts/:

• build_aov_relight_pipeline
• build_deep_holdout_chain
• build_smartvector_paint_propagate
• build_copycat_dehaze
• build_stmap_distortion_envelope
• build_planar_track_clean_plate
• build_3d_camera_track_project
• audit_acescct_consistency_guide

Development

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
pre-commit run --all-files

Tests: 597 passing, 18 skipped (live-Nuke contract tests, run with NUKE_BIN set).

Tags

nuke compositing vfx mcp-server tasks-primitive ocio aov deep-comp tracking copycat-ml

License

MIT