NukeMCP connects AI assistants (Claude, ChatGPT, local LLMs) to a running Nuke session via the Model Context Protocol. Describe what you want in plain English, and the AI creates, connects, and configures nodes in your comp.

Status

Production-ready. Verified end-to-end against Nuke 17.0v1. Full test suite with CI, lint, and coverage. See the roadmap for what's next.

Get Started

Prerequisites: git and Python 3.10+. Nuke is optional at setup time — Nuke 15+ supported, 17+ recommended.

Linux / macOS:

curl -sSL https://raw.githubusercontent.com/kleer001/nuke-mcp/main/scripts/bootstrap.sh | bash

Windows (PowerShell):

powershell -c "irm https://raw.githubusercontent.com/kleer001/nuke-mcp/main/scripts/bootstrap.bat -OutFile bootstrap.bat; .\bootstrap.bat"

The bootstrap clones the repo, installs uv, creates a venv, installs deps, and prints next steps for the Nuke addon and MCP client.

Manual setup (step by step)

1. Clone and install

git clone https://github.com/kleer001/nuke-mcp.git
cd nuke-mcp
uv sync

2. Install the Nuke Addon

Copy the addon into your Nuke scripts directory:

cp nuke_addon/nuke_mcp_addon.py ~/.nuke/

Or add the nuke_addon/ directory to your NUKE_PATH.

Launch Nuke — in the Script Editor, run:

import nuke_mcp_addon
nuke_mcp_addon.start()

A NukeMCP panel appears with Start/Stop button and log. The server listens on port 54321.

3. Configure Your MCP Client

Claude Code: The included .mcp.json configures the server automatically. Run Claude Code from the project root.

Claude Desktop: Go to File > Settings > Developer > Edit Config and add:

{
  "mcpServers": {
    "nuke-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/nuke-mcp", "run", "nuke-mcp"]
    }
  }
}

Other MCP clients (ChatGPT, local LLMs): Any client that supports stdio transport works. Use the same command/args pattern above, or wrap the server in an HTTP bridge for remote clients.

Headless Mode

NukeMCP can auto-discover and launch Nuke without a GUI:

# Auto-discover Nuke, launch headless, connect
uv run nuke-mcp --headless

# Specify a Nuke executable
uv run nuke-mcp --headless --nuke-path /usr/local/Nuke17.0v1/Nuke17.0

# Just find Nuke installations and check licensing
uv run nuke-mcp --discover

Discovery searches standard paths (/usr/local/Nuke*, /Applications/Nuke*), .desktop files, running processes, mounted volumes, and the NUKE_EXE environment variable. It also detects Foundry trial licenses (JWT tokens) and RLM license servers.

Available Tools

Core tools available on all Nuke variants, plus gated tools for NukeX and Nuke 17+. Destructive tools require user confirmation — enforced at the code level, not just in the AI's instructions.

Full tool list

Core (all variants)

Tool	Description	Annotations
get_script_info	Script name, frame range, FPS, colorspace, node count	readOnly
get_node_info	Node class, position, inputs, knob values	readOnly
create_node	Create a node with optional name, knobs, position
modify_node	Set knob values on an existing node	idempotent
delete_node	Delete a node (requires confirmation)	destructive
connect_nodes	Connect output of one node to input of another
position_node	Set node position in the graph	idempotent
auto_layout	Auto-arrange nodes
execute_python	Run arbitrary Python in Nuke (requires confirmation)	destructive
load_script	Open a .nk file (requires confirmation)	destructive
save_script	Save the current script (requires confirmation)	destructive
set_project_settings	Set FPS, colorspace, resolution	idempotent
set_frame_range	Set first/last frame	idempotent

Comp & Rendering

Tool	Description
render_frames	Render a Write node over a frame range
set_proxy_mode	Toggle proxy mode
find_nodes_by_type	Find all nodes of a given class
find_broken_reads	Find Read nodes with missing files
batch_set_knob	Set a knob value on multiple nodes
batch_reconnect	Reconnect multiple nodes to a new input

Templates & LiveGroups

Tool	Description
list_toolsets	List saved toolsets
load_toolset	Load a toolset
save_toolset	Save selected nodes as a toolset
create_live_group	Create a LiveGroup from nodes

NukeX (gated)

Tool	Description
create_tracker	Create a Tracker4 node
solve_tracker	Execute tracking
setup_stabilize	Set tracker to stabilize mode
create_camera_tracker	Create a CameraTracker node
create_3d_scene	Create a Scene node
setup_camera	Create a Camera3 node
setup_scanline_render	ScanlineRender with scene + camera
setup_projection	Camera projection workflow
setup_deep_pipeline	Deep compositing pipeline
setup_deep_merge	Deep merge
convert_to_deep	Flat to deep conversion
setup_copycat	CopyCat ML training node
train_copycat	Train a CopyCat model

Nuke 17+ (gated)

Tool	Description
import_splat	Gaussian splat reader
setup_splat_render	Splat render with camera
setup_bigcat	BigCat ML training (NukeX + 17+)
create_annotation	Create annotation/sticky note
list_annotations	List all annotations

Memory & Events

Tool	Description
read_memory	Read persistent memory files
write_memory	Write persistent memory
log_correction	Log a compositor correction
list_memory	List all memory files
update_project_memory	Snapshot current script settings
subscribe_events	Subscribe to real-time scene events
get_events	Get recent events
clear_events	Clear event log
search_nuke_docs	BM25 search over Nuke docs

Docs & Guides

• Technical Reference — architecture, events, memory system, plugin system, offline dev, version gating
• Best Practices — compositor-focused guide with workflows and troubleshooting
• Roadmap — what's next
• Contributing — how to add tools, write tests, follow codebase patterns

Skills

Skills are multi-step workflow guides that define how Claude should approach complex, repeatable production tasks using NukeMCP. Unlike single tool calls, skills orchestrate sequences of MCP tools, filesystem queries, and user confirmation gates to complete high-level operations safely.

Skills live in the skills/ folder. Invoke one by describing the task to Claude — it will recognise the workflow and follow the skill's phases.

Skill	Description
retarget-fx-shot	Duplicate an FX rig network and remap all file references from one shot's sequences to another's

---

Best Practices — The Recipe Book

Nuke is deep software, and the best way to learn it is from someone who's already been there. BEST_PRACTICES.md is a growing collection of practical recipes — the kind of knowledge that saves you hours.

Every entry follows the same format: what we tried, what surprised us, and what works.

This file is baked into Claude's context, so the AI builds on previous experience instead of starting from scratch. The more you use NukeMCP, the smarter it gets.

Got recipes to share? As you work with NukeMCP, your AI will add entries to its own BEST_PRACTICES.md. If you've accumulated useful ones, open an issue and paste your file — we'll merge the good stuff in for everyone.

Acknowledgments

This project builds on the work of several open-source contributors:

• dughogan/nuke_mcp — the right architecture and the right spirit. Clean, compositor-readable code with a clear socket-based design. Doug Hogan's fxphd course made the concept accessible to the compositing community.
• flowagent-sh/nuke-mcp — demonstrated that the feature set can be production-grade, with camera tracking, deep compositing, and ML integration.
• kleer001/houdini-mcp — the persistent memory system, CLAUDE.md behavioral rules, BM25-based RAG, bidirectional events, and the proof that a DCC MCP can be a serious piece of software engineering.

License

MIT

---

_{NukeMCP is not affiliated with or endorsed by Foundry. Nuke is a trademark of Foundry.}