Installation¶

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.

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.

Optional Dependencies¶

Documentation¶

The site is built with Zensical. To build it locally:

pip install -r requirements.docs.txt
python docs/.scripts/generate_technical_docs.py
python -m zensical serve

The first line also installs the fork of mike that Zensical uses for versioned deploys; pip install -e ".[docs]" alone skips it. The second writes the Technical section into docs/technical/ (gitignored) from the Python package, since Zensical has no gen-files plugin.