# 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:
   ```python
   # 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:
   ```python
   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:
```json
{
  "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.*