Houdini MCP

Installation

Requires Houdini 20.5+ (tested on 20.5, 21.0 and 22.0) and Python 3.10+ outside Houdini.

pip install fxhoudinimcp
python -m fxhoudinimcp install

Restart Houdini and your MCP client. An MCP menu appears in Houdini's menu bar.

install sets up both halves: it writes a Houdini package file into every Houdini packages directory it finds, and registers the server with every MCP client it finds (Claude Code, Claude Desktop, Codex, Copilot CLI, Gemini CLI, Cursor, Windsurf, VS Code, Cline). Use the python -m form: the Python that runs it is the one written into the client config.

An existing fxhoudini client entry pointing at another Python is repointed, and the old value printed.

pip install --upgrade fxhoudinimcp upgrades both halves, since the plugin ships inside the wheel. The exception is a plugin loaded from a git clone, which you update with git.

Uninstalling

pip uninstall alone leaves the package file and the client entry behind, and both then fail silently. Remove them first:

python -m fxhoudinimcp uninstall
pip uninstall fxhoudinimcp

Installing by hand

For a clone, a locked-down machine, or untangling a broken setup.

1. Point Houdini at the plugin. Print the package file for this install, then write it:

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

Don't type the plugin path by hand: it moves whenever the Python environment does. To load the plugin from a clone instead, write the package file yourself (the path must end in /houdini):

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

2. Point your MCP client at the server. Every client runs the same command, <python> -m fxhoudinimcp, where <python> is the absolute path of the Python that has fxhoudinimcp (python -c "import sys; print(sys.executable)"). Clients don't inherit your shell's PATH, and a bare python just shows as "disconnected".

CLI clients register it with their own command. File-based clients take this entry in their config file:

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

Any other stdio client takes <python> -m fxhoudinimcp as its command. python -m fxhoudinimcp install --client-only does this step for you.

Usage

The plugin starts with Houdini's UI (FXHOUDINIMCP_AUTOSTART), and the MCP menu starts, stops and checks it. MCP > Connect a Client... shows the port this session actually got (a second Houdini takes the next free port), copies the command that registers the server with every client found, and lists the manual form for each client.

Then ask for things:

"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"
"Debug why my scene has cooking errors"

Every tool call is one undo step. Tools leave your selection, viewport camera and network editor where they were, so you can keep working in the scene while the assistant does.

Configuration

Houdini-side variables live in the package file install wrote, where every one sits at its default. They win over the same variables in your shell; install keeps your edits when it runs again. Client-side variables go in your MCP client's config.

Troubleshooting

No MCP menu in Houdini. Houdini skipped the package file without saying so. Start it with HOUDINI_PACKAGE_VERBOSE=1 and look for Loading: and Processing: lines for fxhoudinimcp.json. The usual causes:

• the plugin path in the file doesn't exist;
• the file starts with a UTF-8 BOM (PowerShell's Set-Content -Encoding UTF8 adds one);
• another fxhoudinimcp.json in a later packages directory overrides it (fxhoudinimcp houdini-package lists them all, uninstall removes them);
• the Houdini version you launched has no package file (each version reads its own preferences directory).

On Windows, OneDrive can make a desktop-launched and a shell-launched Houdini read different preference directories; the package log shows which one is used.

The client shows "disconnected". Its config names a bare python; use the absolute path.

A documented subcommand seems missing. Check python -m fxhoudinimcp --version: an editable install reports the version it was created at.

The assistant can't reach Houdini. get_houdini_connection_status lists every Houdini serving the plugin and why a connection failed.