Houdini MCP

Control SideFX Houdini from an AI client (Claude, ChatGPT Codex, Gemini) through the Model Context Protocol.

The bridge talks to Houdini's Python API over a local TCP socket.

If no Houdini GUI is running, the bridge starts a headless hython session, so you can work without the UI.

• 20 tools — one for each noun: scene_overview, node_inspect, geometry_inspect, stage_inspect, node_edit, parm_set, connect, cook, execute, render, capture, console, docs, playbar, scene_file, select, hda, pdg, session, batch. A mode argument chooses the action, and every tool takes one item or a list. The modules are in src/bridge/tools/.
• Honest failures — a write that Houdini silently ignored is reported as such, and every error names the next action.
• Documentation — the official Houdini docs for the exact build on this machine, read out of the install by the HoudiniMD engine. No network.

Install

Prerequisites: Python 3.10+. Houdini is optional at setup time.

The script installs uv and the houdinimcp package from PyPI, installs the Houdini plugin, and registers the bridge with the agent harnesses you pick.

Windows

powershell -c "irm https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.bat -OutFile bootstrap.bat; .\bootstrap.bat"

Linux / macOS

curl -sSL https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.sh | bash

At a terminal you get menus: which Houdini release to install for, which harnesses to configure — Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor, opencode, pi. pi reads MCP servers through its pi-mcp-adapter extension.

Have uv already? uv tool install houdini-mcp-server && houdinimcp-install does the same thing.

Working from a clone? Run the installer from the repository root: uv run python -m bridge.onboarding.install. It installs the plugin from that clone, and points every harness at it.

# What is on this machine, as JSON: Houdini releases, harnesses, uv
houdinimcp-install --list

# Every default: newest Houdini, every detected harness
houdinimcp-install --yes

# Explicit, and report what changed
houdinimcp-install --houdini-version 22.0 --harness claude-code --harness codex --yes --json

# Report only, change nothing
houdinimcp-install --dry-run --yes

uv tool install houdini-mcp-server
houdinimcp-install --harness none                              # plugin only
claude mcp add --transport stdio houdini -- houdinimcp-bridge

How it works

MCP client ──stdio──> src/bridge/ ──TCP──> src/houdinimcp/ ──> hou API
                                  └──────> houdinimd_docs ──> $HFS/houdini/help

No Houdini running? The bridge starts hython -> houdinimcp/headless.py

src/bridge/ is the MCP side and holds the installer. src/houdinimcp/ is the plugin, which Houdini loads from a copy in its preferences directory.

The installer also adds a HoudiniMCP shelf with a button that starts and stops the TCP server.

Headless mode gives you every tool except the ones that need a UI: viewport, screenshots and flipbooks. Set HOUDINIMCP_NO_HEADLESS=1 to turn auto-launch off. For those, session with action="start_gui" starts Houdini with its window (and hip= opens a file), then waits for the plugin.

On Windows, a Houdini that the bridge starts reads the same preferences as one started from the Start menu: the bridge sets HOUDINI_USER_PREF_DIR when it is not set. A shell that sets HOME (Git Bash does) otherwise sends Houdini to $HOME\houdiniX.Y.

Contributing

Read AGENTS.md before you change anything. It carries the working rules and links to the short guides in agents/.

Acknowledgements

Built on the work of blender-mcp, capoomgit/houdini-mcp, eetumartola/houdini-mcp, Houdini21MCP and fxhoudinimcp.

MIT licensed.

_{HoudiniMCP is an independent community project. It is not affiliated with, endorsed by, or sponsored by SideFX Software. Houdini and SideFX are trademarks of SideFX Software Inc.}