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.

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¶

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 stops rather than guessing when it cannot know the answer. If several Houdini packages directories exist it lists them and asks, because choosing wrongly produces an install that fails silently:

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

Flag	What it does
`--dry-run`	Report every change, make none
`--houdini-dir DIR`	Which packages directory to write into
`--client-only`	Register a client, leave Houdini untouched. Needs no packages directory, so it works when several exist
`--client auto\\|claude-code\\|claude-desktop\\|both\\|none`	Which client to register. `none` if you wire it up yourself

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.

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.

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.

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:

# Windows (PowerShell)
$env:HOUDINI_PACKAGE_VERBOSE=1; houdini
# Linux / macOS
HOUDINI_PACKAGE_VERBOSE=1 houdini

A working package prints both a Loading: and a Processing: line for fxhoudinimcp.json. Three ways this fails quietly:

A path that does not exist. Houdini skips the package and says nothing. Nothing loads: no menu, no auto-start, no fxhoudinimcp_server module.
A UTF-8 BOM. Houdini's JSON parser rejects a leading BOM and skips the whole package. On Windows, Set-Content -Encoding UTF8 adds one; use -Encoding utf8NoBOM (PowerShell 7+) or an editor that can save without one. The file looks correct either way, which is what makes this one nasty. Both install and houdini-package write without a BOM.
A second fxhoudinimcp.json. Houdini processes every packages directory and the last one wins, so a leftover file can override a fresh install. Both commands warn when they find another one. fxhoudinimcp houdini-package lists every one it can see, and what each points at.

On Windows, note that OneDrive's Documents redirection means a desktop-launched Houdini and a shell-launched one can resolve different preference directories. The package log is what settles which one your Houdini actually reads.

Optional Dependencies¶

MkDocs Documentation¶

For building the documentation locally:

pip install -e ".[mkdocs]"