# Houdini MCP Server

Control [SideFX Houdini](https://www.sidefx.com/) from AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io/).

35 tools for node creation, parameter editing, geometry inspection, scene management, and arbitrary Python execution — all driven by natural language through Claude or any MCP-compatible client.

## Features

- **Node operations** — create, delete, rename, connect, layout, cook, find nodes
- **Parameter control** — get/set values, list parameters, set expressions
- **Geometry inspection** — read points, primitives, bounding boxes, export `.geo`
- **Scene management** — new/open/save scenes, scene info
- **Transform tools** — get/set object transforms
- **Code execution** — run arbitrary Python or HScript inside Houdini
- **Built-in documentation** — 11 comprehensive HOM reference docs + 5 index files, searchable via MCP tools

## Prerequisites

- [Houdini](https://www.sidefx.com/download/) (any edition — Apprentice, Indie, Core, FX)
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Setup

### 1. Start RPYC server in Houdini

Open Houdini's Python Shell (`Windows > Python Shell`) and run:

```python
import hrpyc
hrpyc.start_server(port=18811)
```

Or use the provided helper script:

```python
exec(open("/path/to/houdini-mcp/houdini_setup.py").read())
```

### 2. Configure your MCP client

Add to your MCP client configuration (e.g., `.mcp.json` for Claude Code):

```json
{
  "mcpServers": {
    "houdini": {
      "command": "uv",
      "args": ["--directory", "/path/to/houdini-mcp", "run", "server.py"]
    }
  }
}
```

Replace `/path/to/houdini-mcp` with the actual path to this repo.

### 3. Connect

Call the `houdini_connect` tool first. Then use any of the 35 available tools.

## Claude Code Skill (Optional)

The `claude-skill/` directory contains a Houdini Python reference skill for Claude Code. To use it:

1. Copy `claude-skill/houdini-python.md` to your project's `.claude/commands/` directory
2. The skill provides HOM API reference, SOP/DOP/VOP node guides, and scripting patterns
3. Invoke with `/houdini-python` in Claude Code

## Tools

| Category | Tools |
|----------|-------|
| Connection | `houdini_connect`, `houdini_disconnect` |
| Scene | `houdini_scene_new`, `houdini_scene_open`, `houdini_scene_save`, `houdini_scene_info` |
| Nodes | `houdini_node_create`, `houdini_node_delete`, `houdini_node_rename`, `houdini_node_connect`, `houdini_node_cook`, `houdini_node_info`, `houdini_node_children`, `houdini_node_find`, `houdini_node_layout`, `houdini_node_set_flags` |
| Parameters | `houdini_parm_get`, `houdini_parm_set`, `houdini_parm_list`, `houdini_parm_set_expression` |
| Geometry | `houdini_geo_info`, `houdini_geo_read_points`, `houdini_geo_read_prims`, `houdini_geo_bbox`, `houdini_geo_export` |
| Transforms | `houdini_transform_get`, `houdini_transform_set` |
| Execution | `houdini_execute`, `houdini_hscript` |
| Frame | `houdini_set_frame` |

## How it works

```
┌──────────────┐     MCP (stdio)     ┌──────────────┐     RPYC (TCP)     ┌──────────────┐
│  AI Client   │ ◄─────────────────► │  MCP Server  │ ◄────────────────► │   Houdini    │
│ (Claude etc) │                     │  (server.py) │                     │  (port 18811)│
└──────────────┘                     └──────────────┘                     └──────────────┘
```

The MCP server translates tool calls into RPYC remote procedure calls to Houdini's Python interpreter. Houdini runs an RPYC server (via `hrpyc`) that exposes the full `hou` module.

## License

MIT