Houdini MCP

A Model Context Protocol (MCP) server that seamlessly bridges AI assistants (like Claude, Cursor, Antigravity, and Codecs) directly to a live Houdini Indie/FX session.

This allows your AI to directly act as a Technical Director (TD): creating nodes, wiring networks, querying scene data, simulating physics, and modifying parameters in real-time.

🚀 Features

• 20+ Built-in Tools: Read parameters, create nodes, wire VOPs/SOPs, capture errors, save .hip files, etc.
• Advanced Python/HScript Execution: Provides an escape hatch for the AI to run raw Python against the Houdini Object Model (hou).
• Fully Local: Communicates over stdio and 127.0.0.1. No proprietary scene data leaves your machine.

---

🛠️ 1. Installation

Houdini uses an internal Python environment, but our MCP server runs externally. We need to install the bridge dependencies.

1. Clone or download this repository.
2. Double-click setup.bat (Windows).
   • This will automatically find your Python 3 installation, create a .venv virtual environment, and install fastmcp and rpyc==4.1.0 (which matches Houdini's internal RPyC version).

(Note: If you are doing this manually, simply run pip install fastmcp rpyc==4.1.0)

---

🎩 2. Houdini Setup

You must tell your open Houdini session to listen for the AI's commands. There are two ways to do this:

Option A: Automatic Startup (Recommended)

You can configure Houdini to automatically start the AI connection in the background every time it launches so you never have to do it manually.

1. Go to your Houdini preferences folder (e.g., Documents/houdini21.0/ or Documents/houdini19.5/).
2. Open or create the scripts folder.
3. Inside scripts, create a file named pythonrc.py and add this code:

   # Start hrpyc server for AI MCP integration
   try:
       import hrpyc
       hrpyc.start_server(port=18811)
       print("[Houdini MCP] hrpyc listener successfully started on port 18811")
   except Exception:
       pass
   

Option B: Manual Startup

If you only want to run the connection when you explicitly need it:

1. Open Houdini (Indie, FX, or Core).
2. Go to Windows > Python Shell (or press Alt + Shift + P).
3. Paste the following snippet and hit Enter:

   import hrpyc
   hrpyc.start_server(port=18811)
   

---

🤖 3. Connecting to your AI (Client Setup)

You need to register this server with your MCP-compatible AI host. You will need the absolute paths to both the Python executable in the .venv and the houdini_mcp_server.py script.

🔹 For Claude Desktop

Open your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server:

{
  "mcpServers": {
    "houdini": {
      "command": "C:\\path\\to\\-Houdini-s-MCP-\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\-Houdini-s-MCP-\\houdini_mcp_server.py"]
    }
  }
}

🔹 For Cursor / Cline

1. Open Cursor Settings > Features > MCP Servers.
2. Click + Add New MCP Server.
3. Name: Houdini
4. Type: command
5. Command: "C:\path\to\-Houdini-s-MCP-\.venv\Scripts\python.exe" "C:\path\to\-Houdini-s-MCP-\houdini_mcp_server.py"

🔹 For Antigravity

Open ~/.gemini/config/mcp_config.json and add the same JSON block as the Claude Desktop example above.

---

📝 Example Prompts to try with your AI

Once connected, try asking your AI:

• "What is the current frame range of my open Houdini scene?"
• "Create a procedural house out of a box and a tube, boolean them together, and drop them into an RBD bullet solver."
• "Find all nodes in my network that currently have cooking errors and tell me what the errors are."
• "Make the sphere at /obj/geo1/sphere1 5 times bigger."

---

Built with FastMCP and RPyC.