dcc-mcp-nuke

Agent workflow

AI agents should use the shared gateway through dcc-mcp-cli; IDE users may continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.

Install or update the CLI

dcc-mcp-cli is the preferred control path for every shell-capable agent. If it is missing, ask the user before installing the latest official release:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"

Keep an official build current through the release manifest:

dcc-mcp-cli update check
dcc-mcp-cli update apply

update apply downloads and stages the latest CLI for the next launch. It does not update a running dcc-mcp-server; update that server in its own environment.

dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type nuke
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'

dcc-types reports release-catalog support; list reports live sessions. If a tool belongs to an inactive progressive skill, call dcc-mcp-cli load-skill <skill-name> --dcc-type nuke before retrying. For post-task improvement, attach a stable session id with --meta-json, query dcc-mcp-cli stats --range 24h --session-id <task-id>, then pass the bounded evidence to the review_skill_improvement prompt from dcc-mcp-skills-creator.

Nuke adapter for the DCC Model Context Protocol. It embeds a Streamable HTTP MCP server in Nuke and uses Nuke's main-thread execution API for scene tools.

See install.md for the agent-first install, verify, upgrade, and receipt-driven uninstall workflow on Windows, macOS, and Linux.

Host flavors: Nuke, NukeX, and Nuke Studio

One package covers all three Foundry entry points. Nuke, NukeX, and Nuke Studio ship from one installation, share one embedded Python interpreter and one ~/.nuke plug-in profile, and install once. Core registers all three as executable stems of a single dcc-type (nuke), so there is no second package, entry point, or release channel to install.

What differs between them is the feature surface available at runtime. The adapter classifies the running entry point as one of three host flavors and reports it as server capability metadata:

dcc-mcp-cli call nuke_diagnostics__host_flavor --dcc-type nuke --json '{}'

Detection prefers nuke.env, then the executable name, and treats an importable hiero module as a supporting signal rather than a decisive one. Set DCC_MCP_NUKE_HOST_FLAVOR only to override detection for a host that really runs that flavor; unrecognized values are ignored.

Studio-only skills are gated, not silently unavailable

A bundled skill that needs the Studio surface declares it in its manifest:

metadata:
  dcc-mcp:
    host-flavors: [nukestudio]

On a nuke or nukex session that skill stays discoverable, so an agent can still see the capability exists, but it will not load. dcc-mcp-cli load-skill nuke-studio-timeline --dcc-type nuke fails with an explicit veto naming both the required flavor and the current one, and calling the tool directly returns the same capability_unavailable error. A Studio skill never fails silently.

nuke-studio-timeline is the first Studio skill. It inspects open projects, sequences, track counts, and frame range through the Hiero surface, read-only, and reports an explicit studio_surface_unavailable error when a Studio build does not expose the expected API instead of skipping it.

Probe the host with nuke_diagnostics__host_flavor first when the entry point is unknown.

Automated Houdini AOV compositing

This real Nuke session progressively isolates Albedo, Sun, Diffuse, Glossy, and Emission passes, then merges them into the approved composite. The 35-layer, 114-channel EXR source was rendered from a solar-system scene built in Houdini with dcc-mcp-houdini; Nuke reads the Houdini AOVs rather than bundled sample footage.

Nuke loads the lifecycle-managed plug-in path and asks the operating system for an available instance port. Use dcc-mcp-cli list or the stable gateway at http://127.0.0.1:9765/mcp to discover and connect to the running instance. Set DCC_MCP_NUKE_PORT only when a fixed direct port is required.

The bundled nuke-script skill can open an existing absolute .nk path, inspect bounded node topology and knob values, sample per-channel AOV statistics, and explicitly save the current script. The nuke-node-graph skill adds non-clearing node CRUD, exact input connections, and readback- verified static knob edits while rejecting executable knobs. The nuke-text-layout skill creates or updates one bounded Text2 label, maps requested pixel size through Nuke's effective global_font_scale, and returns verified node position, text box, and alignment readback with rollback on mismatch. It rejects arbitrary node classes, Python, Tcl, scripts, expressions, callbacks, bracket/backslash/control text, animated/keyed/expression-bearing required knobs, and UI input while preserving ordinary Unicode labels. Dynamic-state probes must return their documented boolean, curve-list, and non-negative key-count shapes; unsupported or unobservable probe results fail closed before mutation. Scale, box, and position readback must use finite non-boolean numeric values with exact bounded shapes; malformed readback fails closed and rolls back. Releases use a canonical tag and exact-main identity check, one digest-bound wheel/sdist bundle, and a minimal-OIDC publisher in release.yaml and the GitHub pypi environment. Immediately before publishing, the workflow force-refreshes authoritative main and tag refs into an isolated namespace and repeats the identity checks. CI obtains the Install SOP schema from the isolated minimum- Core environment used for the installed-wheel smoke rather than its ambient interpreter.

The nuke-node-assets skill packages reusable, versioned Gizmos with an explicit public knob interface, instantiates saved assets, and validates live instances. Its registered tools use DCC_MCP_NUKE_PLUGIN_ROOT, stable ids and versions, bounded typed knobs, and reject executable callbacks.

The nuke-layered-compositing skill supports ordered global and Cryptomatte-scoped gain, saturation, edge-feather, and bounded albedo-fill adjustments without changing pixels outside the selected material.