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: fpt-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

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

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.

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