fxhoudinimcp 2.0.0

    

fxhoudinimcp

The most comprehensive MCP server for SideFX Houdini.
179 tools across 22 categories, covering every major Houdini context.

                    

Table of Contents

• About
• Features
• Architecture
• Installation
• Usage
• Environment Variables
• Development
• Contact

About

A comprehensive MCP (Model Context Protocol) server for SideFX Houdini. Connects AI assistants like Claude directly to Houdini's Python API, enabling natural language control over scene building, simulation setup, rendering, and more.

179 tools, 8 resources, and 6 workflow prompts out of the box.

Features

Architecture

flowchart LR
    subgraph Client[" 🤖 AI Client "]
        direction TB
        A1("Claude Desktop")
        A2("Cursor / VS Code")
        A3("Claude Code")
    end

    subgraph MCP[" ⚡ FXHoudini MCP Server "]
        direction TB
        B1("🔧 179 tools")
        B2("📦 8 Resources")
        B3("💬 6 Prompts")
    end

    subgraph Houdini[" 🔶 SideFX Houdini "]
        direction TB
        C1("🌐 hwebserver")
        C2("📡 Dispatcher")
        C3("🎛️ hou.* Handlers")
        C1 --> C2 --> C3
    end

    Client -. "MCP Protocol · stdio" .-> MCP
    MCP -. "HTTP / JSON · port 8100" .-> Houdini

    classDef clientBox fill:#f0f4ff,stroke:#b8c9e8,stroke-width:1px,color:#2d3748,rx:12,ry:12
    classDef mcpBox fill:#eef6f0,stroke:#a8d5b8,stroke-width:1px,color:#2d3748,rx:12,ry:12
    classDef houdiniBox fill:#fff5f0,stroke:#e8c4a8,stroke-width:1px,color:#2d3748,rx:12,ry:12

    classDef clientNode fill:#dbe4f8,stroke:#96b0dc,stroke-width:1px,color:#2d3748,rx:8,ry:8
    classDef mcpNode fill:#d4edda,stroke:#82c896,stroke-width:1px,color:#2d3748,rx:8,ry:8
    classDef houdiniNode fill:#fde4d0,stroke:#e0a87c,stroke-width:1px,color:#2d3748,rx:8,ry:8

    class Client clientBox
    class MCP mcpBox
    class Houdini houdiniBox
    class A1,A2,A3 clientNode
    class B1,B2,B3 mcpNode
    class C1,C2,C3 houdiniNode

Uses Houdini's built-in hwebserver. No custom socket servers, no rpyc. Uses hdefereval.executeInMainThreadWithResult() to safely run hou.* calls on the main thread.

Installation

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+
• MCP SDK (mcp package) 1.8+

1. Install the MCP Server

From PyPI:

pip install fxhoudinimcp

From source:

pip install -e .

Or with development dependencies:

pip install -e ".[dev]"

2. Install the Houdini Plugin

The PyPI package does not contain the Houdini plugin. pip install fxhoudinimcp installs only the MCP server that Claude talks to. The Houdini-side half lives in this repository's houdini/ directory, so clone the repo even if you installed the server from PyPI:

git clone https://github.com/healkeiser/fxhoudinimcp

Option A: Houdini package (recommended)

1. Copy houdini/fxhoudinimcp.json to your Houdini packages directory:

   • Windows: %USERPROFILE%/Documents/houdiniXX.X/packages/
   • Linux: ~/houdiniXX.X/packages/
   • macOS: ~/Library/Preferences/houdini/XX.X/packages/

2. Edit the copy and replace the placeholder FXHOUDINIMCP value with the absolute path to this repository's houdini directory:

   { "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.

The package file is also where you configure the plugin. It ships every Houdini-side setting 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.

Two ways this step fails silently, both worth knowing:

• A path that does not exist. Houdini skips a package whose path cannot be resolved without printing anything. Nothing loads: no MCP 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 Set-Content -Encoding utf8NoBOM (PowerShell 7+) or an editor that can save without a BOM. The file looks correct either way, which is what makes this one nasty.

To see what Houdini actually did with your package, 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.

Option B: Manual copy

Copy the contents of houdini/ into your Houdini user preferences directory so that:

• scripts/python/fxhoudinimcp_server/ is on Houdini's Python path
• python3.Xlibs/uiready.py auto-starts the server (copy the folder matching your Houdini's Python version: 3.11 for Houdini 20.5 and 21.0, 3.13 for Houdini 22.0)
• MainMenuCommon.xml adds the MCP menu to Houdini's menu bar

3. Configure Your MCP Client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "fxhoudini": {
      "command": "python",
      "args": ["-m", "fxhoudinimcp"],
      "env": {
        "HOUDINI_HOST": "localhost",
        "HOUDINI_PORT": "8100"
      }
    }
  }
}

Claude Code (global — available in every project):

claude mcp add --scope user fxhoudini -- python -m fxhoudinimcp

Or to scope it to a single project, add a .mcp.json in the project root:

{
  "mcpServers": {
    "fxhoudini": {
      "command": "python",
      "args": ["-m", "fxhoudinimcp"]
    }
  }
}

[!TIP] If Claude Desktop reports the server as disconnected, replace "python" with the full absolute path to your Python executable. Claude Desktop does not always inherit your system PATH. Find it with:

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

Then use the result in your config, e.g. "command": "C:\\Program Files\\Python311\\python.exe". After any config change, fully quit Claude Desktop (system tray → Quit) and relaunch.

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, Server Status).

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"

Environment Variables

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run linter
ruff check python/

# Run tests
pytest

# Run integration tests inside a real Houdini (requires a license seat;
# uses the newest installed Houdini, override with the HYTHON env var).
# Works on Windows, macOS, and Linux:
python tests/run_integration.py
# Convenience wrappers: tests/run_integration.ps1 / tests/run_integration.sh

# Contribute this machine's Houdini builds to the node-availability table and
# regenerate the version annotations in server_instructions.md:
python tools/gen_node_versions.py
python tools/gen_node_versions.py --check   # verify the table against this machine
HYTHON=/path/to/hython python tools/gen_node_versions.py   # one specific build

tools/node_versions.json accumulates. It records which builds have been sampled and what node types each had, so one installed Houdini is enough: your build merges into the shared evidence and the annotations are derived from everything sampled so far. A contributor with a single Houdini produces exactly the same table as someone with six. If a version has never been sampled by anyone, the generator says so rather than guessing, and --check reports only contradictions with the builds you actually have.

That evidence file is ~1 MB and is not shipped. The generator also writes python/fxhoudinimcp/data/sampled_versions.json, a few hundred bytes listing only which versions have been sampled, which does ship: the server compares the connected Houdini against it at startup and warns when a version has never been checked, so a marker like (21.0+) silently covering a future 23.0 becomes visible instead. get_houdini_connection_status reports the same thing. It is advisory: build_network(dry_run=True) validates node types against the running Houdini and cannot go stale.

If Red Giant / Maxon Universe is installed, its OpenFX plug-in crashes hou initialisation on Houdini 20.5.487 and later, so hython cannot start at all. Set HOUDINI_DISABLE_OPENFX_DEFAULT_PATH=1 when running any of the above. This is a Houdini/Universe conflict, not something this repo causes.

Unit tests mock hou and run anywhere. The integration suite in tests/integration/ executes all 179 commands against live Houdini via hython — including end-to-end user scenarios (procedural modeling, simulation, animation, lookdev) — and prints per-command timing and coverage reports; it is skipped automatically when hou is not available. tests/integration/perf_sweep.py benchmarks handlers on large scenes, and python tests/integration/bridge_e2e.py validates the full HTTP transport (real hwebserver in hython driven by the MCP server's own bridge).

How It Works

1. Houdini Plugin (houdini/): Runs inside Houdini's Python environment. Registers @hwebserver.apiFunction endpoints that receive JSON commands. Uses hdefereval.executeInMainThreadWithResult() to safely execute hou.* calls on the main thread.

2. MCP Server (python/fxhoudinimcp/): A standalone Python process using FastMCP. Exposes 179 tools, 8 resources, and 6 prompts via the MCP protocol. Forwards tool calls to Houdini over HTTP.

3. Bridge (python/fxhoudinimcp/bridge.py): Async HTTP client that sends commands to Houdini's hwebserver and deserializes responses. Handles connection errors and timeouts.

Contact

Project Link: fxhoudinimcp

License

MIT