NukeMCP

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.

Related MCP server: Houdini MCP Server

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.

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.

Core (all variants)

Comp & Rendering

Templates & LiveGroups

NukeX (gated)

Nuke 17+ (gated)

Memory & Events

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.

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.