fxhoudinimcp 2.26.0

Table of Contents

• About
• Installation
• Usage
• Configuration
• Security
• Development
• Contact

About

An MCP server for SideFX Houdini: it lets an AI assistant build networks, set up simulations, inspect USD stages and render, through Houdini's own Python API. It works with any MCP client: Claude, Codex, Copilot, Gemini, Cursor, Windsurf, VS Code, Cline and others.

215 tools, 8 resources, and 9 prompts serving 31 written workflow guides out of the box.

flowchart LR
    subgraph Client[" 🤖 AI Client "]
        direction TB
        A1("Claude · Codex · Copilot · Gemini")
        A2("Cursor · Windsurf · VS Code · Cline")
        A3("any stdio MCP client")
    end

    subgraph MCP[" ⚡ FXHoudini MCP Server "]
        direction TB
        B1("🔧 215 tools")
        B2("📦 8 Resources")
        B3("💬 9 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

The plugin runs on Houdini's built-in hwebserver and executes every hou.* call on the main thread through hdefereval. The MCP server is a separate process your AI client starts; it relays tool calls to the plugin over loopback HTTP.

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.

Usage

The plugin starts with Houdini's UI (FXHOUDINIMCP_AUTOSTART), and the MCP menu starts, stops and checks it. MCP > Connect a Client... shows the port this session actually got (a second Houdini takes the next free port), copies the command that registers the server with every client found, and lists the manual form for each client.

Then ask for things:

"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"
"Debug why my scene has cooking errors"

Every tool call is one undo step. Tools leave your selection, viewport camera and network editor where they were, so you can keep working in the scene while the assistant does.

Configuration

Houdini-side variables live in the package file install wrote, where every one sits at its default. They win over the same variables in your shell; install keeps your edits when it runs again. Client-side variables go in your MCP client's config.

Security

A connection to this server is a shell inside your Houdini session: execute_python runs arbitrary code, and there is no authentication or per-tool permission. It is built for one artist's workstation and an MCP client they trust.

• The plugin binds to loopback unless FXHOUDINIMCP_BIND says otherwise.
• Requests with an Origin header (a web page) or a non-loopback Host (DNS rebinding) are refused.
• FXHOUDINIMCP_PROJECT_ROOT confines the files the tools open, save, import, export or install. It does not check paths written into parameters (a File SOP, a ROP output), and execute_python / execute_hscript are not sandboxed.
• Recovery from a bad change is undo, one step per tool call.

Development

See CONTRIBUTING.md for what CI checks.

pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest                                  # unit tests, hou mocked
python tests/run_integration.py         # live suite in hython; needs a license seat, HYTHON picks the build
python tests/integration/gui_session_check.py   # against a running GUI Houdini
python tools/gen_node_versions.py       # add this machine's Houdini builds to the node table
python tools/gen_node_domains.py        # after gen_node_versions
python tools/gen_required_commands.py
python tools/gen_prompt_vocab.py        # node tables in the prompts; edit tools/prompt_vocab.json, not the markdown

With Red Giant / Maxon Universe installed, set HOUDINI_DISABLE_OPENFX_DEFAULT_PATH=1, or its OpenFX plug-in crashes hython on 20.5.487 and later.

Layout: the plugin is in houdini/ (handlers under scripts/python/fxhoudinimcp_server/handlers/), the MCP server in python/fxhoudinimcp/ (tools, bridge, prompts). Prompts are in prompts/markdown/: instructions/ is sent to every client, workflows/ holds one guide per SideFX help scope (pyro.md pairs with pyro/), shared/ holds fragments.

What a call costs. Every command waits for a main-thread tick in Houdini, so call count, not work, sets a session's speed (Houdini 22.0.368, idle scene):

Contact

Project Link: fxhoudinimcp

License

MIT