Skip to main content
Glama

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 17

The 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-plugin

This 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 status

To 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-mcp

Claude 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 8765

It 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.com address:

    brew install cloudflared
    cloudflared tunnel --url http://127.0.0.1:8765
  • For 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

get_app_info, list_formats, execute_python

Projects

list_projects, get_project, new_project, open_project, save_project, close_project, undo, redo

Bins and clips

list_bin, create_bin, import_media, get_clip, rename_bin_item, move_bin_item, delete_bin_item, set_clip_version, reconnect_media

Sequences and tracks

list_sequences, get_sequence, create_sequence, update_sequence, add_track, update_track, delete_track

Shots

list_track_items, get_track_item, add_clip_to_track, update_track_item, delete_track_items, razor, add_effect

Tags

list_project_tags, add_tag, remove_tag

UI

get_selection, set_selection, open_in_timeline, open_in_viewer, get_playhead, set_playhead

Export

list_export_presets, run_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_MCP_PORT

Hiero and server

7392

HIERO_MCP_HOST

Hiero and server

127.0.0.1

HIERO_MCP_TOKEN

Hiero and server

contents of ~/.hiero_mcp/token

HIERO_MCP_HTTP_TOKEN

HTTP server

contents of ~/.hiero_mcp/http_token

HIERO_MCP_HOME

Hiero and server

~/.hiero_mcp

HIERO_MCP_DISABLE

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 --live

It 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 tools
add_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_projectA
Destructive

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_itemB
Destructive

Remove a bin, clip or sequence from the project (undoable).

Inputs: path (required), project. Returns: object

delete_trackB
Destructive

Remove a track and everything on it (undoable).

Inputs: track (required), kind, project, sequence. Returns: object

delete_track_itemsC
Destructive

Remove shots from a track (undoable).

Inputs: items (required), kind, track, project, +1 more. Returns: object

execute_pythonA
Destructive

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_infoB
Read-only

Hiero product, version, mode (Hiero / Nuke Studio), Python version and open projects.

Inputs: no named parameters. Returns: object

get_clipB
Read-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_playheadC
Read-only

Current viewer frame and the sequence being viewed.

Inputs: no named parameters. Returns: object

get_projectC
Read-only

Project settings: frame rate, output format, OCIO, views, export root, undo/redo state, sequences.

Inputs: project. Returns: object

get_selectionA
Read-only

What the artist has selected in the active timeline and in the project bin.

Inputs: no named parameters. Returns: object

get_sequenceB
Read-only

Sequence details and tracks; with include_items also every track item and soft effect.

Inputs: project, sequence, include_items. Returns: object

get_track_itemC
Read-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_binC
Read-only

Tree of bins, clips, sequences and tags under a bin ("" is the project root).

Inputs: depth, project, bin_path. Returns: object

list_export_presetsB
Read-only

Export (processor) presets available locally and in the project.

Inputs: project. Returns: result

list_formatsA
Read-only

All image formats Hiero knows about (name, width, height, pixel aspect).

Inputs: no named parameters. Returns: result

list_projectsA
Read-only

Open projects with path, unsaved-changes flag and counts of sequences and clips.

Inputs: no named parameters. Returns: result

list_project_tagsB
Read-only

Tags available to the project: its own Tags bin plus Hiero's preset tags (Status, Review, Shots...).

Inputs: project. Returns: result

list_sequencesB
Read-only

Sequences in one project (or all open projects) with duration, frame rate and format.

Inputs: project. Returns: result

list_track_itemsB
Read-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_tagC
Destructive

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_exportA
Destructive

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

    C2.9/5.0

    Scored across 45 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers