fxhoudinimcp

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.

168 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("🔧 168 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+ (tested on 21.0)

• 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

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

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"]
    }
  }
}

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

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.

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

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 167 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