Skip to main content
Glama

nuke-mcp

tests tools mcp python nuke license

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.

Salt Spill 90-second demo

Demo script + screenplay: DEMO.md.

Related MCP server: After Effects MCP

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

Available Tools

45 tools
auto_layoutB
Idempotent

Auto-arrange the node graph layout.

Args: selected_only: if True, only arrange selected nodes.

Inputs: selected_only.

clear_expressionA
Idempotent

Remove an expression or animation from a knob, leaving it at its current value.

Args: node: node name. knob: knob name to clear.

Inputs: knob (required), node (required).

connect_nodesA
Idempotent

Connect two nodes. For Merge nodes, defaults to B pipe (input 1).

Args: from_node: source node (output). to_node: target node (input). input_index: which input on the target. defaults to 0, or 1 for Merge nodes.

Inputs: to_node (required), from_node (required), input_index.

create_nodeB

Create a node and optionally wire it to an existing node.

Args: type: Nuke node class (Grade, Blur, Merge2, Read, Write, etc.) name: optional name. Nuke auto-names if omitted. connect_to: name of a node to connect as input 0. for Merge nodes, connects to B pipe.

Inputs: type (required), name, connect_to.

create_rotoB

Create a Roto or RotoPaint node connected to the input.

Args: input_node: node to roto on top of. roto_type: Roto or RotoPaint.

Inputs: input_node (required), roto_type.

delete_nodeA
Destructive

Delete a node from the script.

Args: name: node to delete. confirm: must be True to actually delete. call with False first to preview.

Inputs: name (required), confirm.

diff_compA
Read-only

Compare the current comp to a previous snapshot. Shows nodes added, removed, and knobs changed. Call snapshot_comp first.

Args: snapshot_id: ID from a previous snapshot_comp call.

Inputs: snapshot_id (required). Returns: Output of ``diff_comp``: lists of added / removed / changed nodes. Each ``added…

disconnect_node_inputC
Idempotent

Disconnect a specific input on a node.

Args: node: node name. input_index: which input to disconnect (0-based).

Inputs: node (required), input_index (required).

find_nodesC
Read-only

Search for nodes by type, name pattern, or error state.

Args: type: filter by node class (e.g. 'Grade', 'Read'). pattern: filter by name substring (case-insensitive). errors_only: if True, only return nodes with errors.

Inputs: type, pattern, errors_only.

get_knobC
Read-only

Read a knob value from a node.

Args: node: node name. knob: knob name (e.g. 'size', 'mix', 'file', 'channels').

Inputs: knob (required), node (required).

get_script_infoA
Read-only

Get current script metadata: path, frame range, fps, format, colorspace, node count.

Inputs: no named parameters.

list_channelsB
Read-only

List all channels/layers available at a node's output, grouped by layer.

Args: node: node name to inspect channels of.

Inputs: node (required).

list_keyframesB
Read-only

List all keyframes on a knob. Returns frame/value pairs.

Args: node: node name. knob: knob name to inspect.

Inputs: knob (required), node (required).

list_nodesA
Read-only

List all nodes in the script, or children of a Group node.

Args: root: optional Group node name to list children of.

Inputs: root.

list_precompsB
Read-only

Find all precomp Write/Read pairs in the script.

Inputs: no named parameters.

list_profilesA
Read-only

List every skill profile with its description, tool count, and current-loaded state.

Pass the returned name to load_profile to surface the profile's tools at runtime. Profiles already in loaded=True are visible right now.

Inputs: no named parameters.

list_roto_shapesB
Read-only

List all shapes and strokes in a Roto or RotoPaint node.

Args: node: name of a Roto or RotoPaint node.

Inputs: node (required).

load_profileA

Surface every tool in profile name. Idempotent -- loading an already-loaded profile is a no-op.

Emits notifications/tools/list_changed after the flip so the client refreshes its tool surface.

Args: name: profile name (call list_profiles for the catalog).

Inputs: name (required).

load_scriptB
Destructive

Open a Nuke script. Replaces current script.

Args: path: .nk file to open. confirm: must be True to proceed. call with False first to preview.

Inputs: path (required), confirm.

modify_nodeA
Idempotent

Rename a node. Checks for expressions that reference this node and optionally updates them to use the new name.

Args: name: current node name. new_name: new name to set. update_expressions: auto-fix expressions referencing the old name. default True.

Inputs: name (required), new_name, update_expressions.

read_compA
Read-only

Read the node graph (or a subtree). Returns nodes with type, connections, non-default knob values, and error state.

For large comps (200+ nodes), use summary=True for a compact overview (names and types only, no knobs), or use offset/limit to paginate.

Args: root: read children of this node only (e.g. a Group name). omit for entire script. depth: how many levels deep to recurse into groups. default 999. summary: if True, return only name/type/connections per node, skip knobs. faster for large comps. type: filter to only this node class (e.g. 'Grade', 'Read'). offset: skip this many nodes (for pagination). default 0. limit: max nodes to return. 0 means all. use with offset to page through large comps.

Inputs: root, type, depth, limit, +2 more.

read_node_detailA
Read-only

Deep inspection of a single node. Returns all non-default knobs, input/output connections, expressions, animation state, and error info. For Groups/Gizmos, also shows internal node structure.

Args: name: node name to inspect.

Inputs: name (required). Returns: Detailed node payload used by ``read_node_detail``. Adds inputs, knob dict, met…

render_framesA
Destructive

Render frames through a Write node.

By default this returns immediately with a task_id and runs the render in the background; poll tasks_get(task_id) for progress, tasks_cancel to interrupt, or wait for the terminal state notification.

Pass synchronous=True to keep the pre-B2 blocking shape (returns the full RenderResult once the render finishes). That path is wire-compatible with existing callers.

Args: write_node: name of Write node. uses first Write in script if omitted. first_frame: start frame. uses script range if omitted. last_frame: end frame. uses script range if omitted. confirm: must be True to render. call with False to preview. synchronous: block until done and return RenderResult (B2 back-compat). Defaults to False -- use the async Task flow.

Inputs: confirm, last_frame, write_node, first_frame, +1 more. Returns: Result of a render through a Write node. Wire shape ``{rendered, frames: [first…

save_scriptB

Save the script. If path is given, saves as a new file.

Args: path: optional file path for save-as. omit to save in place.

Inputs: path.

scene_deltaA
Read-only

Compare current scene state against a previous hash.

If unchanged, returns {"changed": False, "hash": prev_hash} with no graph enumeration leaking into the response. If changed, returns the full digest body with changed=True.

Args: prev_hash: the hash from a previous scene_digest (or scene_delta) call.

Inputs: prev_hash (required).

scene_digestA
Read-only

Compact fingerprint of the script: counts by class, errors, warnings, selection, active viewer, display node, plus an md5 hex[:8] hash for delta comparison.

Stable across no-op turns -- pair with scene_delta to skip re-rendering large response payloads when nothing has changed.

Inputs: no named parameters.

set_expressionA
Idempotent

Set a TCL expression on a knob. The expression is evaluated per-frame.

Common expressions: frame, frame/24.0, sin(frame*0.1), [value other_node.knob]

A regex pre-flight rejects expressions that wrap forbidden Python calls in [python ...] callouts or invoke TCL system/exec/ unlink directly.

Args: node: node name. knob: knob name to set expression on. expression: Nuke TCL expression string.

Inputs: knob (required), node (required), expression (required).

set_frame_rangeB
Idempotent

Set the timeline frame range and/or current frame.

Args: first: first frame number. last: last frame number. current: jump to this frame.

Inputs: last, first, current.

set_keyframeB
Idempotent

Set a keyframe on a knob at a specific frame. Creates animation if the knob is not already animated.

Args: node: node name. knob: knob name. frame: frame number. value: value at that frame.

Inputs: knob (required), node (required), frame (required), value (required).

set_knobB
Idempotent

Set a knob value on a node.

Args: node: node name. knob: knob name. value: value to set. type depends on the knob.

Inputs: knob (required), node (required), value (required).

set_node_positionB
Idempotent

Set x/y positions for one or more nodes in the DAG. Use for manual layout control -- position the main pipe vertically and branch side chains to the right.

Args: positions: JSON array of {node, x, y} objects. example: '[{"node":"Grade1","x":0,"y":200},{"node":"Blur1","x":200,"y":200}]'

Inputs: positions (required).

setup_denoiseC

Create a Denoise node with production defaults.

Args: input_node: node to denoise.

Inputs: input_node (required).

setup_mergeB

Merge foreground over background. Auto-connects fg to B pipe.

Args: fg: foreground node name. bg: background node name. operation: merge operation (over, plus, multiply, screen, etc.)

Inputs: bg (required), fg (required), operation.

setup_precompA

Set up a precomp: creates a Write node for the source, and a Read node that reads the rendered output back in. Downstream nodes get rewired to the Read.

The Write path is auto-generated from the script name and precomp name if not specified.

Args: source_node: node whose output to precomp. name: label for the precomp (used in file path). defaults to source node name. path: explicit output path. auto-generated if omitted.

Inputs: source_node (required), name, path.

setup_transformC

Create a transform node.

Args: input_node: node to transform. operation: Transform, CornerPin2D, Reformat, or Tracker4.

Inputs: input_node (required), operation.

setup_writeA

Create a Write node connected to input_node with production defaults.

A3: typed dispatch -- the addon validates file_type against the allowlist (exr/tiff/png/jpeg/mov/dpx) and rejects any path with a .. traversal component.

Args: input_node: node to connect as input. path: output file path (use #### for frame padding). file_type: exr, tiff, png, jpeg, mov, or dpx. colorspace: output colorspace.

Inputs: path (required), input_node (required), file_type, colorspace.

set_viewer_lutA
Idempotent

Switch the viewer's display LUT/colorspace.

Args: lut: LUT or colorspace name (e.g. 'sRGB', 'Cineon', 'None').

Inputs: lut (required).

shuffle_channelsC

Create a Shuffle node to move channels between layers.

Args: input_node: source node. from_layer: source layer (e.g. 'diffuse', 'specular', 'depth'). to_layer: target layer. defaults to 'rgba'.

Inputs: from_layer (required), input_node (required), to_layer.

snapshot_compA
Read-only

Take a snapshot of the current comp state. Returns a snapshot_id you can pass to diff_comp later to see what changed.

Snapshots are stored server-side (max 5). Use before making changes.

Inputs: no named parameters.

tasks_cancelA
Destructive

Cancel an in-flight task.

Sets state="cancelled" on the disk record AND signals the addon-side worker (for renders) so it stops between frames. Cancelling an already-terminal task is a no-op -- the response carries the existing state unchanged.

Inputs: id (required).

tasks_getB
Read-only

Fetch a single task by id.

Inputs: id (required).

tasks_listB
Read-only

List recent tasks, newest first.

Inputs: limit.

tasks_resumeA
Read-only

Resume a task that's awaiting input.

TODO(B2c): wired up once a tool actually parks in input_required. Until commit 4 ships an async render and a future commit adds elicitation, every Task either succeeds or fails synchronously, so resume has nothing to drive. Returns a stub status so clients can probe capability without crashing.

Inputs: id (required).

unload_profileA

Disable every tool in profile name. core is locked on -- unloading it would strip the read paths and the load_profile tool itself.

Args: name: profile name to disable.

Inputs: name (required).

view_nodeA

Set the viewer to display a specific node's output.

Args: node: name of the node to view.

Inputs: node (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 45 tools

    Disambiguation4/5

    Tools mostly target distinct operations, with clear parameter descriptions. Some overlap exists between read_comp/list_nodes/find_nodes and between snapshot_comp/scene_digest, but descriptions distinguish them well.

    Naming Consistency5/5

    All tool names use snake_case with predictable verb_noun or noun_verb patterns (list_*, read_*, set_*, setup_*, tasks_*). No mixed conventions.

    Tool Count2/5

    45 tools is excessive for the domain's core needs, and at least one tool (tasks_resume) is an explicit stub with no current function, indicating some tools don't earn their place.

    Completeness4/5

    Core CRUD for nodes, knobs, expressions, keyframes, rendering, and precomps is present. Minor gaps exist (e.g., roto shape editing, node enable/disable, grouping), but most workflows are covered.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers