Houdini MCP

MCP server that lets AI agents (Claude Code, Cursor, etc.) directly control SideFX Houdini — create nodes, set parameters, execute Python, capture viewports, render frames, and more.

Built on Model Context Protocol + RPyC. Supports multi-instance, instance pooling, and includes a WebUI dashboard.

Features

• 57 MCP tools covering scene, nodes, parameters, geometry, rendering, viewport, and more

• Multi-instance — run multiple Houdini sessions on different ports simultaneously

• Instance pooling — pre-warm idle Houdini instances, acquire on demand, skip the startup wait

• Health diagnostics — detect hung/busy/dead Houdini via Win32 API + RPyC ping (never hangs)

• WebUI dashboard — manage sessions, configuration, startup scripts, and tool toggles from a browser

• Auto-discovery — MCP server finds running Houdini instances automatically

• Non-destructive setup — startup hook is a single line in 456.py, fully reversible

Related MCP server: fxhoudinimcp

Requirements

• Windows (Win32 APIs used for screen capture and process diagnostics)

• Python 3.11+

• SideFX Houdini 20.5+ (tested with 20.5 and 21.0)

Quick Start

1. Install

git clone https://github.com/OtakuSquirrel/houdini-mcp.git
cd houdini-mcp

# Option A: run install.bat (creates venv + installs everything)
install.bat

# Option B: manual
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[webui]"

2. Configure your MCP client

Add to your Claude Code project settings (.claude/settings.local.json):

{
  "mcpServers": {
    "houdini": {
      "command": "D:/path/to/houdini-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "houdini_mcp"],
      "cwd": "D:/path/to/houdini-mcp"
    }
  }
}

3. Start working

The first time an agent calls a Houdini tool, the MCP server will:

1. Auto-install the startup hook into your Houdini prefs (one-time, non-destructive)

2. Launch Houdini and wait for RPyC to be ready

3. Connect and start executing tool calls

No manual setup needed. Just ask your AI agent to do something in Houdini.

WebUI Dashboard

# Start the dashboard
Windows_webui.bat
# or manually:
.venv\Scripts\python.exe -m houdini_mcp.webui --port 9800

Dashboard — sessions, ports, processes at a glance

HouConfig — port range, search paths, startup hook injection

MCP Tools — enable/disable tools per category

AgentConfig — generate MCP client config for Claude Code, Cursor, etc.

Instance Pooling

Houdini takes 11-37 seconds to start. The pool tools let you pre-warm instances:

warm_pool([{"count": 3}])          # Launch 3 idle Houdini instances
get_pool_status()                   # → 3 idle, 0 active
acquire_from_pool()                 # → Grab one, now 2 idle, 1 active
disconnect_houdini()                # → Release back to idle pool

# When Houdini freezes:
is_houdini_healthy()                # → verdict: "hung", CPU 0%
adopt_idle()                        # → Kill frozen instance, grab an idle one

Available Tools (57)

How It Works

AI Agent ←(stdio)→ MCP Server ←(RPyC/TCP)→ Houdini
                         ↕
                    WebUI Dashboard

• MCP Server starts idle. On first tool call, it auto-discovers a Houdini RPyC listener on the configured port range (default 18811-18899) and connects.

• Houdini runs a startup hook (456.py) that calls hrpyc.start_server() to expose the full hou module over RPyC.

• WebUI is a separate FastAPI app that reads the shared config and session registry at ~/houdini_mcp/.

Troubleshooting

Houdini not connecting — Run install_startup_scripts() or use the WebUI Config page, then restart Houdini.

Port conflicts — Use scan_ports() or the WebUI Dashboard to see port status. Run cleanup_stale_sessions() to remove dead entries.

RPyC version mismatch — This project requires rpyc>=4.1,<5. Houdini ships RPyC 4.x internally. RPyC 6.x is incompatible.

Viewport screenshot fails — Requires GUI mode. Does not work with hython (headless).

License

MIT