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)

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/
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 - scripts/456.py runs on scene load - 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 (.mcp.json in project root):

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

[!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.

Optional Dependencies¶

MkDocs Documentation¶

For building the documentation locally:

pip install -e ".[mkdocs]"