Houdini MCP

Requirements

• Houdini 20.5+ (tested on 21.0)
• Python 3.10+
• MCP SDK (mcp package) 1.8+

Install dev dependencies

pip install -e ".[dev]"

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

Installation

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

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/

1. Edit the JSON file to set FXHOUDINIMCP to point to the houdini directory in this repo.

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) - toolbar/fxhoudinimcp.shelf appears in your shelf

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

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 toggle it manually via the MCP Server shelf tool.

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"

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.

Environment Variables

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

```

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).