houdini-mcp

Drive a live Houdini session from an MCP client (Claude, Grok, Codex, …).

Houdini 22-first. Pipeline-safe by design: this is hands in houdini-bin, not a shot database — it does not talk to any asset-management or production-tracking API, and it does not ship HDAs.

Backlog: issues

Upstream seed: kleer001/houdini-mcp (MCP bridge + TCP plugin). This fork changed the contract.

What it is

AI client  --stdio MCP-->  houdini_mcp_server.py  --TCP :9876-->  plugin in houdini-bin  -->  hou

The plugin is per Houdini process. The MCP client config is per user. Ship it as its own package if you vendor it into a facility environment — it is not meant to live inside a shared HDA library.

Related MCP server: Houdini MCP Server

H22 contract

• Start hook: $HOUDINI_USER_PREF_DIR/python3.13libs/uiready.py (not scripts/pythonrc.py)

• Houdini package JSON: PYTHONPATH only — never path: onto HOUDINI_PATH

• No hou.ui.desktops() / shelf UI from MCP (H22 plus a site 123.py has crashed houdini-bin)

• LOP nodes have no setRenderFlag

• execute_code returns {executed, stdout, stderr, error, traceback} — never drops TCP

• Viewport capture = Scene Viewer flipbook. OpenGL ROP is OBJ-only. Desktop grab runs outside houdini-bin.

• Solaris viewport: set_hydra_renderer("xpu"|"cpu"|"vk"|"storm"). Do not restartRenderer + sleep + viewwrite on the MCP thread. USD look-through is set_viewport_camera("/world/cam").

Install

git clone https://github.com/tmdag/houdini-mcp
cd houdini-mcp
uv sync
python scripts/install.py --houdini-version 22.0

install.py copies the plugin into your Houdini preferences directory and writes the package JSON that auto-starts it. It honours HOUDINI_USER_PREF_DIR; pass --prefs-dir if you keep prefs somewhere unusual, and --dry-run to see what it would touch first.

Claude Code / Claude Desktop:

{
  "mcpServers": {
    "houdini": {
      "command": "/path/to/houdini-mcp/.venv/bin/python",
      "args": ["/path/to/houdini-mcp/houdini_mcp_server.py"]
    }
  }
}

Grok:

[mcp_servers.houdini]
command = "/path/to/houdini-mcp/.venv/bin/python"
args = ["/path/to/houdini-mcp/houdini_mcp_server.py"]
enabled = true

[mcp_servers.houdini.env]
HOUDINIMCP_NO_HEADLESS = "1"
HOUDINIMCP_PROFILE = "stage"

In Houdini, Python Shell if uiready missed this session:

import houdinimcp
houdinimcp.start_server()

Profiles

191 tools is ~17k tokens of schema before any work starts, so the advertised surface is trimmed by default. Everything still exists — the profile only changes what is listed, and the server tells the client how many tools it is hiding and how to get them back.

HOUDINIMCP_PROFILE:

• stage (default) — 82 tools: Solaris/LOP + inspect + cook + screenshot + execute_code + everything the server instructions reference

• sop — /obj modeling extras too

• all — all 191

Anything named in the server's own instructions is guaranteed to survive stage; tests/test_tool_surface.py fails the build otherwise.

Platform support

Windows and macOS paths are implemented and unit-tested, but nobody has run them end to end yet.

Tuning

Offline Houdini docs

Index your Houdini's help (not a random GitHub dump):

python scripts/index_hfs_help.py

Uses $HFS/houdini/help (hom.zip, nodes.zip, loose .txt). Output is gitignored.

Reload handlers (H22 stays up)

python scripts/install.py --houdini-version 22.0

Then reload_plugin. Do not restart houdini-bin for handler changes. Do not importlib.reload the TCP server module (QTimer).

TCP frames are HMC1 + length + JSON. The bridge still speaks bare JSON until the plugin answers in HMC1, so an older houdini-bin keeps working. A second MCP client does not steal the first session; ping.clients / peer_warning say so.

Live smoke (H22 already running)

Does not boot Houdini. Against a GUI houdini-bin with the plugin on :9876:

HOUDINIMCP_LIVE=1 pytest tests/test_live_hydra_smoke.py -q

Fails if list_hydra_renderers 404s, set_hydra_renderer current ≠ requested, USD look-through isn't /world/cam, or the flipbook isn't tagged Karma XPU.

License

MIT (upstream). Not affiliated with SideFX.