hiero-mcp
Provides tools for reading and editing Foundry Nuke Studio/Hiero 17 projects, including bins, clips, sequences, tracks, shots, tags, soft effects, exports, and UI controls in a running Hiero session.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hiero-mcp what shots are in my current sequence?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hiero-mcp
An MCP server for Foundry Hiero / Nuke Studio 17. It lets any MCP-capable agent (Claude, ChatGPT / Codex, Gemini and others) read and edit the projects, bins, sequences, tracks, shots, tags, soft effects and exports of a running Hiero session.
Agent (Claude / Codex / Gemini / ChatGPT)
│ MCP (stdio, or HTTP through a tunnel)
▼
hiero-mcp (this package, Python ≥ 3.11, outside Hiero)
│ JSON over a TCP socket on 127.0.0.1:7392 + shared token
▼
hiero_mcp_bridge plugin (inside Hiero, main thread)
│ hiero.core / hiero.ui
▼
Hiero 17The MCP server runs on the same machine as Hiero. Each artist installs the package and registers it with their agent.
Requirements
Hiero, Hiero Player or Nuke Studio 17.x (tested on 17.1v2, Python 3.11).
uv (
curl -LsSf https://astral.sh/uv/install.sh | sh).
Related MCP server: resolve-ai-bridge
Installation
The examples install straight from GitHub. If you install from a wheel file instead (for example one downloaded from a website), replace git+https://github.com/hramirezedc/hiero-mcp with the wheel's path or URL.
1. Hiero plugin (once per machine)
uvx --from git+https://github.com/hramirezedc/hiero-mcp hiero-mcp install-pluginThis copies hiero_mcp_startup.py into ~/.nuke/Python/Startup/ and the hiero_mcp_bridge package into ~/.nuke/. It also creates the shared token in ~/.hiero_mcp/token. Restart Hiero, then check the connection:
uvx --from git+https://github.com/hramirezedc/hiero-mcp hiero-mcp statusTo skip the plugin for one session, launch Hiero with HIERO_MCP_DISABLE=1. To remove it: hiero-mcp uninstall-plugin.
2. Register the server with your agent
In every case the command is uvx --from git+https://github.com/hramirezedc/hiero-mcp hiero-mcp. Desktop apps don't always inherit your shell PATH: if they can't find uvx, use its full path (which uvx).
Claude Code
claude mcp add hiero -- uvx --from git+https://github.com/hramirezedc/hiero-mcp hiero-mcpClaude Desktop: in ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"hiero": {
"command": "uvx",
"args": ["--from", "git+https://github.com/hramirezedc/hiero-mcp", "hiero-mcp"]
}
}
}OpenAI Codex CLI: in ~/.codex/config.toml
[mcp_servers.hiero]
command = "uvx"
args = ["--from", "git+https://github.com/hramirezedc/hiero-mcp", "hiero-mcp"]Gemini CLI: in ~/.gemini/settings.json
{
"mcpServers": {
"hiero": {
"command": "uvx",
"args": ["--from", "git+https://github.com/hramirezedc/hiero-mcp", "hiero-mcp"]
}
}
}Remote clients (HTTP + Cloudflare Tunnel)
You only need this for clients that run in the cloud and connect by URL, such as ChatGPT connectors or claude.ai. The local agents above use stdio and need no network setup.
1. Start the HTTP server on the Hiero machine:
hiero-mcp --transport http --port 8765It serves http://127.0.0.1:8765/mcp and requires a token, stored in ~/.hiero_mcp/http_token. Show it with hiero-mcp http-token; replace it with hiero-mcp http-token --rotate. A client can send the token in either of two ways:
Authorization: Bearer <token>header, for clients that let you set headers;inside the URL,
https://<host>/<token>/mcp, for clients that only accept a URL. Treat that URL like a password.
Over HTTP, execute_python is disabled unless you start the server with --allow-python.
2. Expose it with a tunnel. A Cloudflare Tunnel gives you a public HTTPS address without opening ports on your router.
To try it out, a quick tunnel gives you a random
https://….trycloudflare.comaddress:brew install cloudflared cloudflared tunnel --url http://127.0.0.1:8765For a fixed address on your own domain, use a named tunnel:
cloudflared tunnel login cloudflared tunnel create hiero cloudflared tunnel route dns hiero hiero.example.com cloudflared tunnel run --url http://127.0.0.1:8765 hiero
3. Connect the client to https://hiero.example.com/mcp with the bearer token, or to https://hiero.example.com/<token>/mcp.
The tunnel only provides HTTPS and a public address. The token is what keeps other people out. If you also put the hostname behind Cloudflare Access, the client has to be able to send Access service-token headers; most MCP clients cannot.
Tools
Area | Tools |
Application |
|
Projects |
|
Bins and clips |
|
Sequences and tracks |
|
Shots |
|
Tags |
|
UI |
|
Export |
|
Every change is one undo step in Hiero. Tools that delete or overwrite are marked with destructiveHint, so agents ask before using them. Trims keep a shot's playback speed, and move_to is an absolute timeline frame.
Configuration
Variable | Used by | Default |
| Hiero and server |
|
| Hiero and server |
|
| Hiero and server | contents of |
| HTTP server | contents of |
| Hiero and server |
|
| Hiero | unset |
Development
uv sync
uv run pytest
uv run hiero-mcp status
uv run python scripts/live_check.py # with Hiero open: runs every tool in a project named "mcp_test"To publish a release on the website, bump version in pyproject.toml, then run:
uv run python scripts/release.py --base-url https://<your-site>/hiero-mcp --liveIt runs the tests (plus the live check with --live) and stops at the first failure. If everything passes, it writes dist/site/: the wheel, checksums, a package index for uvx --index <base-url>/simple/ hiero-mcp@latest, the license, and download.html, the block to paste into the download page. Upload the whole folder to the base URL, keeping its structure.
After changing the plugin, run uv run hiero-mcp install-plugin and restart Hiero, or reload hiero_mcp_bridge.commands from execute_python.
src/hiero_mcp/server.py defines the MCP tools. src/hiero_mcp/hiero_plugin/hiero_mcp_bridge/commands.py implements them with the Hiero API. Each tool has a command with the same name and parameters, and the tests check that they stay in sync.
License
Freeware by Toolbox Design, all rights reserved: free to use, including commercially, but not to modify, redistribute or sell. See LICENSE.
Available Tools
45 toolsadd_clip_to_trackC
Cut a clip into a track at timeline_in (default: after the last item). Overlapping items are overwritten.
Inputs: clip (required), kind, track, project, +5 more. Returns: object
add_effectB
Add a soft effect (Nuke node class, e.g. "Grade", "Transform", "Text2") over a shot or a frame range.
`knobs` sets node knob values, e.g. {"white": 1.2}. Without item or range it covers the whole sequence.
Inputs: effect_type (required), item, knobs, track, +4 more. Returns: object
add_tagA
Tag a clip, sequence, track or shot. Reuses a project tag of the same name if it exists.
Target: `clip`; or `sequence` alone; or `sequence`+`track`; or `sequence`+`track`+`item`.
Inputs: tag (required), clip, icon, item, +6 more. Returns: object
add_trackC
Add a video or audio track to a sequence.
Inputs: kind, name, project, sequence. Returns: object
close_projectADestructive
Close a project. Refuses if it has unsaved changes unless save is true.
Inputs: project (required), save. Returns: object
create_binB
Create a bin, including any missing parent bins (e.g. "Footage/Day1").
Inputs: bin_path (required), project. Returns: object
create_sequenceB
Create a sequence in a bin. format is a name from list_formats; timecode_start is in frames.
Inputs: name (required), format, project, bin_path, +4 more. Returns: object
delete_bin_itemBDestructive
Remove a bin, clip or sequence from the project (undoable).
Inputs: path (required), project. Returns: object
delete_trackBDestructive
Remove a track and everything on it (undoable).
Inputs: track (required), kind, project, sequence. Returns: object
delete_track_itemsCDestructive
Remove shots from a track (undoable).
Inputs: items (required), kind, track, project, +1 more. Returns: object
execute_pythonADestructive
Run Python inside Hiero's main thread for anything the other tools do not cover.
`hiero` is pre-imported (hiero.core, hiero.ui). Assign to a variable named `result`
to return a JSON-serialisable value; stdout, stderr and any traceback are returned too.
Inputs: code (required). Returns: object
get_app_infoBRead-only
Hiero product, version, mode (Hiero / Nuke Studio), Python version and open projects.
Inputs: no named parameters. Returns: object
get_clipBRead-only
Clip details: media path, resolution, timecode, versions, tags and media metadata.
`clip` is a bin path ("Footage/A001"), a clip name or a GUID.
Inputs: clip (required), project. Returns: object
get_playheadCRead-only
Current viewer frame and the sequence being viewed.
Inputs: no named parameters. Returns: object
get_projectCRead-only
Project settings: frame rate, output format, OCIO, views, export root, undo/redo state, sequences.
Inputs: project. Returns: object
get_selectionARead-only
What the artist has selected in the active timeline and in the project bin.
Inputs: no named parameters. Returns: object
get_sequenceBRead-only
Sequence details and tracks; with include_items also every track item and soft effect.
Inputs: project, sequence, include_items. Returns: object
get_track_itemCRead-only
Full shot details: ranges, handles, speed, media, versions, linked items, tags, metadata.
Inputs: item (required), kind, track, project, +1 more. Returns: object
import_mediaB
Import files or folders (image sequences, movies) as clips into a bin, creating it if needed.
Inputs: paths (required), project, bin_path. Returns: object
list_binCRead-only
Tree of bins, clips, sequences and tags under a bin ("" is the project root).
Inputs: depth, project, bin_path. Returns: object
list_export_presetsBRead-only
Export (processor) presets available locally and in the project.
Inputs: project. Returns: result
list_formatsARead-only
All image formats Hiero knows about (name, width, height, pixel aspect).
Inputs: no named parameters. Returns: result
list_projectsARead-only
Open projects with path, unsaved-changes flag and counts of sequences and clips.
Inputs: no named parameters. Returns: result
list_project_tagsBRead-only
Tags available to the project: its own Tags bin plus Hiero's preset tags (Status, Review, Shots...).
Inputs: project. Returns: result
list_sequencesBRead-only
Sequences in one project (or all open projects) with duration, frame rate and format.
Inputs: project. Returns: result
list_track_itemsBRead-only
Shots on one track, or on every track of kind, with timeline and source ranges.
Inputs: kind, track, project, sequence. Returns: result
move_bin_itemB
Move a bin, clip or sequence into another bin ("" is the project root).
Inputs: path (required), to_bin (required), project. Returns: object
new_projectC
Create a new empty project.
Inputs: name. Returns: object
open_in_timelineC
Open a sequence or clip in a timeline tab.
Inputs: clip, project, sequence. Returns: object
open_in_viewerC
Show a sequence or clip in the viewer.
Inputs: clip, project, sequence. Returns: object
open_projectC
Open a .hrox project from disk.
Inputs: path (required). Returns: object
razorC
Cut every unlocked track (or one track) at a frame.
Inputs: time (required), kind, track, project, +1 more. Returns: object
reconnect_mediaB
Reconnect offline media for a clip, or for every clip in a sequence, from a folder.
Inputs: path (required), clip, project, sequence. Returns: object
redoB
Redo the last undone action in a project.
Inputs: project. Returns: object
remove_tagCDestructive
Remove a tag (by name or GUID) from a clip, sequence, track or shot.
Inputs: tag (required), clip, item, kind, +3 more. Returns: object
rename_bin_itemC
Rename a bin, clip or sequence by its bin path.
Inputs: path (required), new_name (required), project. Returns: object
run_exportADestructive
Export a sequence, or selected shots, with a named export preset (may overwrite files on disk).
track_items: [{"track": 0, "item": "shot010"}]. `export_root` overrides the preset's root for this run only.
Asynchronous by default; Hiero's export queue shows progress.
Inputs: preset (required), project, sequence, export_root, +2 more. Returns: object
save_projectB
Save a project, or save it to a new .hrox path ("save as") when path is given.
Inputs: path, project. Returns: object
set_clip_versionB
Change a clip's active version: "up", "down", "max", "min" or a version index.
Inputs: clip (required), project, version. Returns: object
set_playheadC
Move the viewer playhead to a frame.
Inputs: time (required). Returns: object
set_selectionB
Select shots in the timeline. items: [{"track": 0, "item": "shot010", "kind": "video"}].
Inputs: items (required), project, sequence. Returns: object
undoC
Undo the last action in a project.
Inputs: project. Returns: object
update_sequenceC
Rename a sequence or change its frame rate, format, start timecode or in/out points.
Inputs: name, format, in_time, project, +4 more. Returns: object
update_trackB
Rename, enable/disable, lock/unlock a track; set blend mode (video) or volume 0-1 (audio).
Inputs: track (required), kind, name, locked, +6 more. Returns: object
update_track_itemA
Edit a shot: rename, enable, retime, move (move_to = new timeline in, keeps duration), trim, version, swap clip.
Trims keep playback speed: `timeline_in`/`timeline_out` and `source_in`/`source_out` trim the head or tail.
Source frames are relative to the start of the clip (0 = first frame of the media).
Inputs: item (required), kind, name, track, +11 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
Most tools map to distinct resource/action pairs across projects, bins, clips, sequences, tracks, shots, tags, selection and viewer. A few close pairs exist (get_clip vs get_track_item, update_sequence vs update_track_item, the various list_* tools), but descriptions make the boundaries mostly clear. execute_python is an explicit catch-all and does not substantially muddy the dedicated tools.
The set is predominantly consistent snake_case verb_noun naming (list_projects, create_sequence, update_track_item, add_tag). Minor deviations include new_project instead of create_project, and standalone verbs such as undo, redo and razor. These are readable and predictable overall.
With 45 tools this is a very heavy surface for a single MCP server, even for a complex DCC integration. Many list/get variants and separate tag, selection, viewer and effect tools make the set harder to navigate than necessary. Some consolidation would improve usability.
Core lifecycle coverage is strong for projects, bins, clips, sequences, tracks and track items, and export/tag/selection/viewer basics are present. Notable gaps remain around effects (add only, no update/delete/list), export job status/cancellation, and project settings editing. execute_python can work around these gaps, but they are still visible omissions.
Maintenance
Related MCP Connectors
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Remote MCP server for audio stem separation, denoise, reverb, and MIDI export.
Related MCP Servers
- FlicenseBqualityCmaintenanceMCP server for inspecting and controlling Blackmagic Fusion Studio through its scripting API.452-
- AlicenseBqualityAmaintenanceLets AI clients inspect and control DaVinci Resolve projects via MCP tools.46795 npm54MIT
- AlicenseAqualityCmaintenanceEnables MCP-compatible agents to inspect and control SideFX Houdini scenes, including node management, parameter edits, connections, Python execution, and HIP file operations over stdio or Streamable HTTP.15MIT
- AlicenseCqualityBmaintenanceEnables MCP clients to interact with SideFX Houdini through a local-only plugin, supporting command execution and customizable workflows.2132MIT