nuke-mcp
Provides tools for interacting with Foundry Nuke compositing software, enabling AI agents to read comps, build comp-domain primitives (AOV, deep, distortion, tracking), manage color spaces, run long jobs as tasks, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nuke-mcp setup a basic aov merge pipeline for my render"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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-modeopen()and friends insideexecute_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 |
| |
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 | 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 | (all) |
Tasks primitive | Disk-persisted state machine: | core |
Skill profiles | Paginated tool surface. Default = | core |
Pydantic outputs |
| (cross-cutting) |
OCIO / ACEScct |
| color |
AOV pipeline |
| aov |
Deep workflow |
| deep |
Distortion / STMap |
| distortion |
Tracking |
| tracking |
CopyCat ML |
| copycat |
Audit |
| 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/LinuxNuke addon setup
Copy the nuke_plugin/ contents to ~/.nuke/nuke_mcp_addon/:
~/.nuke/
nuke_mcp_addon/
__init__.py
addon.py
menu.pyAdd 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
Open Nuke.
Start the MCP addon: Nodes > MCP > Start Server.
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 auditsTool surface
96 tools across 10 profiles. Open src/nuke_mcp/profiles.py for the full mapping.
Profile | Tools | What's in it |
| 45 | Reads, graph mutations, knobs, expressions, keyframes, render, script, roto, viewer, scene digest, profile loader, Tasks meta |
| 4 |
|
| 7 | Keying, colour-correction, OCIO/ACEScct primitives |
| 3 |
|
| 7 | 2D + 3D tracking primitives + |
| 6 | Deep primitives + |
| 4 | Lens distortion envelope, STMap, IDistort, SmartVector propagate |
| 5 | CopyCat training (Task), inference, dehaze macro, Cattery registry |
| 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-renderArchitecture
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 APISafety
execute_python runs through an AST + regex scanner that blocks:
nuke.scriptClose,nuke.scriptClear,nuke.scriptExit,nuke.exit,nuke.delete,nuke.removeAllKnobChangedos.remove,os.unlink,shutil.rmtree,os.systemsubprocess.Popen / run / callWrite-mode
open()(AST-detected, not regex-fragile)Indirection:
getattr,__import__,import asaliases,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_pipelinebuild_deep_holdout_chainbuild_smartvector_paint_propagatebuild_copycat_dehazebuild_stmap_distortion_envelopebuild_planar_track_clean_platebuild_3d_camera_track_projectaudit_acescct_consistency_guide
Development
pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
pre-commit run --all-filesTests: 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 toolsauto_layoutBIdempotent
Auto-arrange the node graph layout.
Args: selected_only: if True, only arrange selected nodes.
Inputs: selected_only.
clear_expressionAIdempotent
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_nodesAIdempotent
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_nodeADestructive
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_compARead-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_inputCIdempotent
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_nodesCRead-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_knobCRead-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_infoARead-only
Get current script metadata: path, frame range, fps, format, colorspace, node count.
Inputs: no named parameters.
list_channelsBRead-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_keyframesBRead-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_nodesARead-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_precompsBRead-only
Find all precomp Write/Read pairs in the script.
Inputs: no named parameters.
list_profilesARead-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_shapesBRead-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_scriptBDestructive
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_nodeAIdempotent
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_compARead-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_detailARead-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_framesADestructive
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_deltaARead-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_digestARead-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_expressionAIdempotent
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_rangeBIdempotent
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_keyframeBIdempotent
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_knobBIdempotent
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_positionBIdempotent
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_lutAIdempotent
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_compARead-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_cancelADestructive
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_getBRead-only
Fetch a single task by id.
Inputs: id (required).
tasks_listBRead-only
List recent tasks, newest first.
Inputs: limit.
tasks_resumeARead-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
Scored across 45 tools
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.
All tool names use snake_case with predictable verb_noun or noun_verb patterns (list_*, read_*, set_*, setup_*, tasks_*). No mixed conventions.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Google Veo AI video generation
MCP server for Producer/Riffusion AI music generation
MCP server for Flux AI image generation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to Nuke for compositing tasks via natural language.14MIT
- AlicenseBqualityDmaintenanceMCP server that lets AI assistants control Adobe After Effects via natural language, enabling composition and layer creation, animation, effects, presets, rendering, and arbitrary ExtendScript execution with Arabic/RTL support.50182 npmMIT
- AlicenseAqualityBmaintenanceMCP server that lets LLMs drive Adobe After Effects, enabling project inspection, comp/layer mutations with undo support, JSON checkpoint/restore, and render-verification of edits.2114,999 npm177MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server for SideFX Houdini that enables AI assistants to interactively control, construct, inspect, and visually verify 3D procedural scenes through tools like node creation, parameter editing, viewport capture, and rendering.MIT