Houdini MCP

Requirements

• Houdini 20.5+ (integration suite green on 20.5.278, 20.5.487, 20.5.613, 20.5.654, 21.0.440 and 22.0.368)
• Python 3.10+, separate from the one inside Houdini
• MCP SDK (mcp package) 1.8+, installed for you as a dependency

Install dev dependencies

pip install -e ".[dev]"

Run integration tests inside a real Houdini (requires a license seat;

Installation

FXHoudini-MCP has two halves: a Houdini plugin that runs inside Houdini, and an MCP server that your AI client starts and which relays to it over loopback. Both ship in the same Python package, so one install command sets up both and one upgrade moves them together.

Install

pip install fxhoudinimcp
python -m fxhoudinimcp install

Then restart Houdini, restart your MCP client, and check the MCP menu in Houdini's menu bar.

install does both halves. It writes a Houdini package file pointing at this exact install, and registers the server with Claude Code and Claude Desktop, whichever it finds, using the absolute path of the Python you ran it with.

Use python -m fxhoudinimcp install rather than the bare fxhoudinimcp install if you have more than one Python. Both work, but the module form is self-correcting: whichever interpreter runs it is the one written into your client config, so if the command runs at all, the path it registers is correct.

Add --dry-run first if you want to see every file it would touch and change nothing.

It asks nothing and it finishes. If you have several Houdini versions, it writes into every packages directory it finds:

Houdini plugin
  Wrote C:\Users\you\Documents\houdini21.0\packages\fxhoudinimcp.json
  Wrote C:\Users\you\Documents\houdini22.0\packages\fxhoudinimcp.json

That is safe rather than lazy. The files are identical and point at the same plugin, so whichever directory your Houdini reads, it finds a correct one. It also settles the Windows case where OneDrive's Documents redirection makes a desktop-launched Houdini and a shell-launched one disagree: both paths get a file, so both work. The cost is an MCP menu in a Houdini version you may not use, which uninstall clears in one go.

Because it never stops to ask, the same command works unchanged from a terminal, from Houdini's MCP menu, or from a setup script. To target one directory only:

python -m fxhoudinimcp install --houdini-dir "~/Documents/houdini22.0/packages"

If your MCP client already has an fxhoudini entry pointing at a different interpreter, it is repointed at this one and the old value is printed. That is the common case after switching Python versions or recreating a virtualenv.

Upgrading later moves both halves at once, because the plugin lives inside the wheel:

pip install --upgrade fxhoudinimcp

The one thing to know: if you told Houdini to load the plugin from a git clone instead of the installed package (see by hand), pip install --upgrade will not move that half. Those two halves are then independent, and the server warns at startup when it finds a plugin older than itself.

Uninstalling

pip uninstall moves neither half. The Houdini package file and the client registration both outlive it, and both fail quietly once the package is gone: a package file pointing at a plugin directory that no longer exists is skipped by Houdini without a word, and a stale client entry shows up only as "disconnected". So take the two halves out first, then the package:

python -m fxhoudinimcp uninstall
pip uninstall fxhoudinimcp

uninstall lists everything it found and asks before removing any of it. Unlike install it does not need to know which Houdini you meant: every fxhoudinimcp.json it finds is a leftover, and the one you forget is exactly what silently overrides your next install. Narrow it with --houdini-dir when you only want one Houdini cleaned.

Installing by hand

install is the recommended route and the rest of this section is the manual equivalent, for contributors working from a clone, locked-down machines, or when something needs untangling. It is the same two halves.

1. Point Houdini at the plugin

fxhoudinimcp houdini-package

That prints the package file with the plugin path filled in for this install, plus the Houdini packages directories found on your machine. Write it with:

fxhoudinimcp houdini-package --write "~/Documents/houdini22.0/packages"

Do not type the plugin path by hand. It lives inside the Python environment you installed into, so it changes if you recreate a virtualenv, switch to uv or pipx, or move between Python versions, and Houdini says nothing when a package path stops resolving. --path-only prints just the path for scripting.

Like install, this deliberately does not pick a packages directory for you, and it warns if another fxhoudinimcp.json exists elsewhere, because Houdini processes every packages directory and lets the last one win. That is how a stale clone silently overrides a fresh install.

Pointing at a clone instead. Contributors, or anyone wanting the plugin tracked by git, can write the package file against a checkout:

{ "env": [ { "FXHOUDINIMCP": "C:/Users/you/code/fxhoudinimcp/houdini" } ],
  "path": "$FXHOUDINIMCP" }

Forward slashes work on every platform. The path must end in /houdini and must contain scripts/, MainMenuCommon.xml and the python3.Xlibs/ folders. Do not do this and the CLI, or the two package files will fight. Remember that pip install --upgrade cannot move a clone.

[!NOTE] Copying houdini/ into your Houdini preferences directory also works, but it is not recommended: pip cannot update a copy, so the plugin drifts behind the server, which is the skew the startup compatibility warning exists to catch. Use a package file so there is one copy of the plugin.

2. Point your MCP client at the server

Both examples need the absolute path to the Python that has fxhoudinimcp installed. Clients start their servers without your shell environment, so a bare python resolves against a PATH they may not share, and the only symptom is the client reporting disconnected with nothing explaining why. Find the path with:

python -c "import sys; print(sys.executable)"

Claude Code (user scope, available in every project):

claude mcp add --scope user fxhoudini -- "C:\Program Files\Python311\python.exe" -m fxhoudinimcp

There is no in-place update. To repoint an existing entry, remove it first:

claude mcp remove fxhoudini -s user

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "fxhoudini": {
      "command": "C:\\Program Files\\Python311\\python.exe",
      "args": ["-m", "fxhoudinimcp"]
    }
  }
}

After any change, fully quit Claude Desktop (system tray → Quit) and relaunch; closing the window is not enough.

To scope the server to a single project instead, add a .mcp.json in the project root with the same mcpServers block.

python -m fxhoudinimcp install --client-only does this step for you, with the right path already filled in, and leaves the Houdini side alone. MCP > Connect a Client... inside Houdini prints the same command along with the port that session actually ended up on.

uses the newest installed Houdini, override with the HYTHON env var).

Contribute this machine's Houdini builds to the node-availability table and

Usage

Launch Houdini normally. The plugin auto-starts once when the UI is ready (controlled by FXHOUDINIMCP_AUTOSTART env var). The startup script uses uiready.py, which stacks correctly with other Houdini packages. You can also control it manually from the MCP menu (Start Server, Stop Server, Connect a Client, Server Status).

MCP > Connect a Client... prints the claude mcp add line for the port this session actually ended up on, and copies it to the clipboard. That matters with more than one Houdini open: a second session moves itself to the next free port, so the configured port and the real one differ.

Startup verifies that Houdini's mcp.health endpoint answers from the current Houdini process before printing that the server is ready. If your assistant cannot reach Houdini after an app restart, call get_houdini_connection_status for structured diagnostics, then relaunch Houdini or align FXHOUDINIMCP_PORT and HOUDINI_PORT if another process owns the port.

Once connected, your AI assistant can:

"Create a procedural rock generator with mountain displacement"
"Set up a Pyro simulation with a sphere source"
"Build a USD scene with a camera, dome light, and ground plane"
"Create an HDA from the selected subnet"
"Debug why my scene has cooking errors"

Configuring the plugin

The package file install writes is also where the Houdini-side settings live. It ships every one of them at its default, so they are all visible in one place: FXHOUDINIMCP_PORT, FXHOUDINIMCP_BIND, FXHOUDINIMCP_AUTOSTART and FXHOUDINIMCP_AUTO_LAYOUT (see Environment Variables for what each does). Two things to know:

- Because the package sets these explicitly, it wins over the same variable set in your shell. Change them here, not in your environment. Houdini's package format has no "only if unset" method, and it rejects JSON comments, so there is no way to ship them inert. - HOUDINI_HOST, HOUDINI_PORT, MCP_TRANSPORT and LOG_LEVEL do not belong here. They are read by the MCP server process that your client launches, not by Houdini, so setting them in this file has no effect -- configure those in your MCP client instead. If you change FXHOUDINIMCP_PORT, set HOUDINI_PORT to match on the client side.

Note that pinning HOUDINI_PORT on the client switches off the port scan. A second Houdini moves itself to the next free port, and the client normally finds it by scanning 8100-8115 and taking the lowest that answers. Pin it only when you want one specific session.

Environment Variables

When Houdini does not load the plugin

No MCP menu means the package file was skipped, and Houdini does that without printing anything. Start it with the package log enabled and look for your file:

```shell

Convenience wrappers: tests/run_integration.ps1 / tests/run_integration.sh

Regenerate the derived search hints and the plugin-command manifest

Regenerate the node vocabulary tables in the workflow prompts. Edit the