kleer001/nuke-mcp

15 stars 14 forks Quality 63 Trend 21MIT

MCP server for Nuke: drive the compositor from Claude and other LLMs. 57 tools — node graph, 3D, deep, tracking, render.

Overview

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. Verified end-to-end against Nuke 17.0v1. Full test suite with CI, lint, and coverage. See the roadmap for what's next. git and Python 3.10+. Nuke is optional at setup time — Nuke 15+ supported, 17+ recommended. The bootstrap clones the repo, installs uv, creates a venv, installs deps, and prints next steps for the Nuke addon and MCP client. Copy the addon into your Nuke scripts directory: Or add the nuke_addon/ directory to your NUKE_PATH. Launch Nuke — in the Script Editor, run: A panel appears with Start/Stop button and log. The server listens on port 54321.

README

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.

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.

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.

View the full README on GitHub

Install

This server does not publish a one-line install command.

Open the repository installation guide New to MCP? Start with the mcpskill.org guide →

Configuration

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