Skip to content
Back to search

houdini-mcp

Houdini MCP Server - Control SideFX Houdini via Model Context Protocol using hrpyc

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oculairmedia--houdini-mcp/badge.svg)](/listings/oculairmedia--houdini-mcp)

HTML

<a href="/listings/oculairmedia--houdini-mcp"><img src="/api/listings/oculairmedia--houdini-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For Codex Desktop on Windows, see the dedicated setup notes in [`docs/codex-windows-setup.md`](docs/codex-windows-setup.md).

Option 1: Houdini Plugin (stdio mode)

The Houdini plugin runs the MCP server directly inside Houdini, using stdio transport. This is the simplest setup with no network configuration required.

**Installation:**

1. Copy the `houdini_plugin` folder to your Houdini packages directory:

   # Windows
   copy houdini_plugin %USERPROFILE%\Documents\houdini20.5\packages\houdini_mcp

   # Linux/Mac
   cp -r houdini_plugin ~/houdini20.5/packages/houdini_mcp

2. Copy the package JSON:

   # Windows
   copy houdini_plugin\houdini_mcp.json %USERPROFILE%\Documents\houdini20.5\packages\

   # Linux/Mac
   cp houdini_plugin/houdini_mcp.json ~/houdini20.5/packages/

3. Install FastMCP in Houdini's Python:

   # Windows (from Houdini's Python)
   hython -m pip install fastmcp

   # Or from Houdini's Python Shell
   import subprocess
   subprocess.run(["pip", "install", "fastmcp"])

4. Restart Houdini and find the "Houdini MCP" shelf

**Usage:** - Click "Start MCP" on the shelf to start the server - Configure your MCP client (Claude Desktop, Cursor, etc.) to use stdio transport - Click "Stop MCP" to stop the server

**MCP Client Configuration (stdio mode):**

{
  "mcpServers": {
    "houdini": {
      "command": "hython",
      "args": ["-c", "from houdini_mcp_plugin import start_server; start_server(use_thread=False)"]
    }
  }
}

Option 2: Docker (Remote mode)

For production use or when Houdini runs on a different machine, use the Docker-based remote mode. This connects to Houdini via hrpyc/RPyC.

**Step 1: Start hrpyc in Houdini**

If you have the Houdini MCP plugin installed: - Click **"Start Remote"** on the Houdini MCP shelf - Use **"Remote Status"** / **"Remote Self-Test"** to confirm the actual bound endpoint, reachability, and firewall guidance - By default the listener binds to `127.0.0.1` (loopback-only). To let a remote client (e.g. the Docker gateway on another host) connect, set `HOUDINI_RPC_BIND_HOST` **and** opt in with `HOUDINI_RPC_TRUSTED_NETWORK=1` or `HOUDINI_RPC_TOKEN`. See [docs/remote-listener.md](docs/remote-listener.md).

Or manually in Houdini's Python Shell (unchanged, still supported):

import hrpyc
hrpyc.start_server(port=18811)

**Step 2: Run the Docker MCP server**

# Clone the repository
git clone https://github.com/oculairmedia/houdini-mcp.git
cd houdini-mcp

# Copy and configure environment
cp .env.example .env
# Edit .env with your Houdini host IP (from Step 1)

# Run with Docker Compose
docker compose up -d

**Step 3: Configure your MCP client**

{
  "mcpServers": {
    "houdini": {
      "url": "http://localhost:3055"
    }
  }
}

**Benefits of Remote Mode:** - Houdini can run on a different machine (e.g., render farm) - MCP server runs in Docker for easy deployment - Full tool set with advanced features - Server-side processing capabilities

Local Development

# Clone and install
git clone https://github.com/oculairmedia/houdini-mcp.git
cd houdini-mcp
pip install -r requirements.txt

# Run
HOUDINI_HOST=192.168.50.90 python -m houdini_mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 565 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Houdini MCP Server
  2. An MCP (Model Context Protocol) server for controlling SideFX Houdini via `hrpyc`, enabling AI assistants like Claude, Cursor, and Letta agents to interact with Houdini sessions.
  3. ## Architecture
  4. ```
  5. +-----------------+ MCP (HTTP) +------------------+ hrpyc:18811 +-------------+
  6. | Claude/Cursor | <------------------> | MCP Server | <------------------> | Houdini |
  7. | Letta Agents | | (Python/FastMCP)| | Session |
  8. +-----------------+ +------------------+ +-------------+
  9. ```
  10. ## Architecture Decisions
  11. Architecture Decision Records (ADRs) live in [`docs/adr/`](docs/adr/):
  12. - [ADR 0001: Language and Process Boundaries](docs/adr/0001-language-and-process-boundaries.md)
  13. — why the server stays Python for `hou` semantics and the FastMCP gateway, the
  14. module boundaries and allowed dependency direction, and the measured thresholds
  15. that would justify a future non-Python sidecar.
  16. ## Features
  17. - **43 MCP tools** across 15 modular categories
  18. - **Full hou module access** - Execute any Houdini Python code remotely
  19. - **Scene management** - Create, load, save scenes
  20. - **Node operations** - Create, delete, modify nodes and parameters
  21. - **Rendering** - Viewport renders, quad views, Karma GPU/CPU support
  22. - **Pane screenshots** - Capture NetworkEditor, SceneViewer, and other panes
  23. - **Scene serialization** - Diff scene states before/after operations
  24. - **Connection management** - Auto-reconnect with exponential backoff + jitter
  25. - **Error handling** - Consistent error responses with recovery hints
  26. - **Response optimization** - Size limits, truncation, AI summarization
  27. - **In-memory caching** - Node type cache with TTL for performance
  28. ## Prerequisites
  29. 1. **Houdini with RPC enabled** - Start Houdini's RPC server:
  30. - In Houdini: `Windows > Python Shell`, then run:
  31. ```python
  32. import hrpyc
  33. hrpyc.start_server(port=18811)
  34. ```
  35. - Or add to your `123.py` startup script for automatic startup
  36. 2. **Network access** - The MCP server must be able to reach Houdini's RPC port (default: 18811)
  37. ## Installation
  38. For Codex Desktop on Windows, see the dedicated setup notes in
  39. [`docs/codex-windows-setup.md`](docs/codex-windows-setup.md).
  40. ### Option 1: Houdini Plugin (stdio mode)
  41. The Houdini plugin runs the MCP server directly inside Houdini, using stdio transport. This is the simplest setup with no network configuration required.
  42. **Installation:**
  43. 1. Copy the `houdini_plugin` folder to your Houdini packages directory:
  44. ```bash
  45. # Windows
  46. copy houdini_plugin %USERPROFILE%\Documents\houdini20.5\packages\houdini_mcp
  47. # Linux/Mac
  48. cp -r houdini_plugin ~/houdini20.5/packages/houdini_mcp
  49. ```
  50. 2. Copy the package JSON:
  51. ```bash
  52. # Windows
  53. copy houdini_plugin\houdini_mcp.json %USERPROFILE%\Documents\houdini20.5\packages\
  54. # Linux/Mac
  55. cp houdini_plugin/houdini_mcp.json ~/houdini20.5/packages/
  56. ```
  57. 3. Install FastMCP in Houdini's Python:
  58. ```bash
  59. # Windows (from Houdini's Python)
  60. hython -m pip install fastmcp
  61. # Or from Houdini's Python Shell
  62. import subprocess
  63. subprocess.run(["pip", "install", "fastmcp"])
  64. ```
  65. 4. Restart Houdini and find the "Houdini MCP" shelf
  66. **Usage:**
  67. - Click "Start MCP" on the shelf to start the server
  68. - Configure your MCP client (Claude Desktop, Cursor, etc.) to use stdio transport
  69. - Click "Stop MCP" to stop the server
  70. **MCP Client Configuration (stdio mode):**
  71. ```json
  72. {
  73. "mcpServers": {
  74. "houdini": {
  75. "command": "hython",
  76. "args": ["-c", "from houdini_mcp_plugin import start_server; start_server(use_thread=False)"]
  77. }
  78. }
  79. }
  80. ```
  81. ### Option 2: Docker (Remote mode)
  82. For production use or when Houdini runs on a different machine, use the Docker-based remote mode. This connects to Houdini via hrpyc/RPyC.
  83. **Step 1: Start hrpyc in Houdini**
  84. If you have the Houdini MCP plugin installed:
  85. - Click **"Start Remote"** on the Houdini MCP shelf
  86. - Use **"Remote Status"** / **"Remote Self-Test"** to confirm the actual bound
  87. endpoint, reachability, and firewall guidance
  88. - By default the listener binds to `127.0.0.1` (loopback-only). To let a
  89. remote client (e.g. the Docker gateway on another host) connect, set
  90. `HOUDINI_RPC_BIND_HOST` **and** opt in with `HOUDINI_RPC_TRUSTED_NETWORK=1`
  91. or `HOUDINI_RPC_TOKEN`. See [docs/remote-listener.md](docs/remote-listener.md).
  92. Or manually in Houdini's Python Shell (unchanged, still supported):
  93. ```python
  94. import hrpyc
  95. hrpyc.start_server(port=18811)
  96. ```
  97. **Step 2: Run the Docker MCP server**
  98. ```bash
  99. # Clone the repository
  100. git clone https://github.com/oculairmedia/houdini-mcp.git
  101. cd houdini-mcp
  102. # Copy and configure environment
  103. cp .env.example .env
  104. # Edit .env with your Houdini host IP (from Step 1)
  105. # Run with Docker Compose
  106. docker compose up -d
  107. ```
  108. **Step 3: Configure your MCP client**
  109. ```json
  110. {
  111. "mcpServers": {
  112. "houdini": {
  113. "url": "http://localhost:3055"
  114. }
  115. }
  116. }
  117. ```
  118. **Benefits of Remote Mode:**
  119. - Houdini can run on a different machine (e.g., render farm)
  120. - MCP server runs in Docker for easy deployment
  121. - Full tool set with advanced features
  122. - Server-side processing capabilities
  123. ### Local Development
  124. ```bash
  125. # Clone and install
  126. git clone https://github.com/oculairmedia/houdini-mcp.git
  127. cd houdini-mcp
  128. pip install -r requirements.txt
  129. # Run
  130. HOUDINI_HOST=192.168.50.90 python -m houdini_mcp
  131. ```
  132. ## Configuration
  133. Environment variables:
  134. | Variable | Default | Description |
  135. |----------|---------|-------------|
  136. | `HOUDINI_HOST` | `localhost` | Houdini machine IP/hostname |
  137. | `HOUDINI_PORT` | `18811` | hrpyc server port |
  138. | `MCP_PORT` | `3055` | MCP server HTTP port |
  139. | `MCP_TRANSPORT` | `http` | Transport type (http, stdio, sse) |
  140. | `LOG_LEVEL` | `INFO` | Logging level |
  141. ## Tool Categories (43 Tools)
  142. The server is organized into 15 modular tool categories in `houdini_mcp/tools/`:
  143. ### Scene & Nodes (`scene.py`, `nodes.py`)
  144. | Tool | Description |
  145. |------|-------------|
  146. | `get_scene_info` | Get current scene info (file, version, nodes) |
  147. | `serialize_scene` | Serialize scene structure for diffs |
  148. | `new_scene` | Create empty scene |
  149. | `save_scene` | Save current scene |
  150. | `load_scene` | Load a .hip file |
  151. | `create_node` | Create a new node |
  152. | `delete_node` | Delete a node by path |
  153. | `get_node_info` | Get node details, parameters, connections, errors |
  154. | `list_children` | List child nodes with connection details |
  155. | `find_nodes` | Find nodes by name pattern or type |
  156. | `list_node_types` | List available node types by category |
  157. ### Wiring & Layout (`wiring.py`, `layout.py`)
  158. | Tool | Description |
  159. |------|-------------|
  160. | `connect_nodes` | Wire nodes together |
  161. | `disconnect_node_input` | Break a connection |
  162. | `reorder_inputs` | Reorder node inputs |
  163. | `set_node_flags` | Set display/render/bypass flags |
  164. | `layout_children` | Auto-layout child nodes |
  165. | `set_node_position` | Set node position in network |
  166. | `set_node_color` | Set node color |
  167. | `create_network_box` | Create network box around nodes |
  168. ### Parameters (`parameters.py`)
  169. | Tool | Description |
  170. |------|-------------|
  171. | `set_parameter` | Set a parameter value |
  172. | `get_parameter_schema` | Get parameter metadata (types, ranges, menus) |
  173. ### Geometry & Materials (`geometry.py`, `materials.py`)
  174. | Tool | Description |
  175. |------|-------------|
  176. | `get_geo_summary` | Get geometry statistics and metadata |
  177. | `create_material` | Create a new material |
  178. | `assign_material` | Assign material to geometry |
  179. | `get_material_info` | Get material parameters and shaders |
  180. ### Rendering (`rendering.py`)
  181. | Tool | Description |
  182. |------|-------------|
  183. | `render_viewport` | Render viewport with camera control |
  184. | `render_quad_view` | Render Front/Left/Top/Perspective views |
  185. | `list_render_nodes` | List all ROPs in /out |
  186. | `get_render_settings` | Get ROP configuration |
  187. | `set_render_settings` | Modify ROP settings |
  188. | `create_render_node` | Create new ROP with settings |
  189. ### Pane Screenshots (`pane_screenshot.py`)
  190. | Tool | Description |
  191. |------|-------------|
  192. | `capture_pane_screenshot` | Capture any Houdini pane as PNG |
  193. | `list_visible_panes` | List capturable panes |
  194. | `capture_multiple_panes` | Batch capture multiple panes |
  195. | `render_node_network` | Navigate to node and capture network |
  196. ### Code Execution (`code.py`, `hscript.py`)
  197. | Tool | Description |
  198. |------|-------------|
  199. | `execute_code` | Execute Python with `hou` available |
  200. | `execute_hscript` | Execute HScript commands |
  201. ### Error Handling (`errors.py`)
  202. | Tool | Description |
  203. |------|-------------|
  204. | `find_error_nodes` | Find all nodes with cook errors |
  205. ### Help & Summarization (`help.py`, `summarization.py`)
  206. | Tool | Description |
  207. |------|-------------|
  208. | `get_houdini_help` | Get help for node types |
  209. | `summarize_response` | AI-summarize large responses |
  210. | `estimate_tokens` | Estimate token count |
  211. | `get_summarization_status` | Get summarization config |
  212. ### Infrastructure (`_common.py`, `cache.py`)
  213. - **Error handling**: `@handle_connection_errors` decorator
  214. - **Connection retry**: Exponential backoff with jitter
  215. - **Response size**: Thresholds, truncation, metadata
  216. - **Caching**: Node type cache with TTL
  217. - **Parallel execution**: `semaphore_gather`, `batch_items`
  218. ## Common Patterns
  219. ### Creating SOP Chains
  220. Build a complete SOP network from scratch:
  221. ```python
  222. # 1. Create geo container
  223. geo = create_node("geo", "/obj", "my_geo")
  224. # 2. Create SOP nodes
  225. sphere = create_node("sphere", geo["node_path"], "sphere1")
  226. xform = create_node("xform", geo["node_path"], "xform1")
  227. color = create_node("color", geo["node_path"], "color1")
  228. out = create_node("null", geo["node_path"], "OUT")
  229. # 3. Wire nodes together
  230. connect_nodes(sphere["node_path"], xform["node_path"])
  231. connect_nodes(xform["node_path"], color["node_path"])
  232. connect_nodes(color["node_path"], out["node_path"])
  233. # 4. Set display flag
  234. set_node_flags(out["node_path"], display=True, render=True)
  235. ```
  236. ### Inserting Nodes Into Existing Chains
  237. Insert a new node between existing connections:
  238. ```python
  239. # 1. Discover existing network
  240. children = list_children("/obj/geo1")
  241. # Find grid and noise nodes from children
  242. # 2. Get current connections
  243. noise_info = get_node_info("/obj/geo1/noise1", include_input_details=True)
  244. # See that noise is connected to grid
  245. # 3. Create new node
  246. mountain = create_node("mountain", "/obj/geo1", "mountain1")
  247. # 4. Rewire: grid → mountain → noise
  248. disconnect_node_input("/obj/geo1/noise1", 0) # Break noise ← grid
  249. connect_nodes("/obj/geo1/grid1", "/obj/geo1/mountain1") # grid → mountain
  250. connect_nodes("/obj/geo1/mountain1", "/obj/geo1/noise1") # mountain → noise
  251. ```
  252. ### Setting Parameters Intelligently
  253. Use parameter schema to set values correctly:
  254. ```python
  255. # 1. Discover parameter metadata
  256. schema = get_parameter_schema("/obj/geo1/sphere1", parm_name="rad")
  257. param = schema["parameters"][0]
  258. # 2. Check parameter type
  259. if param["type"] == "vector":
  260. # Set vector parameter correctly
  261. set_parameter("/obj/geo1/sphere1", "rad", [3.0, 3.0, 3.0])
  262. elif param["type"] == "menu":
  263. # Use menu items
  264. first_option = param["menu_items"][0]["value"]
  265. set_parameter("/obj/geo1/sphere1", "type", first_option)
  266. ```
  267. ### Verifying Results
  268. Always verify geometry after operations:
  269. ```python
  270. # Get comprehensive geometry summary
  271. summary = get_geo_summary(
  272. "/obj/geo1/OUT",
  273. max_sample_points=10,
  274. include_attributes=True
  275. )
  276. # Check cook state
  277. if summary["cook_state"] != "cooked":
  278. # Handle errors
  279. node_info = get_node_info("/obj/geo1/OUT", include_errors=True)
  280. errors = node_info["cook_info"]["errors"]
  281. # Fix errors...
  282. # Verify geometry metrics
  283. assert summary["point_count"] > 0
  284. assert summary["primitive_count"] > 0
  285. # Check bounding box
  286. bbox = summary["bounding_box"]
  287. # Verify expected size/position
  288. ```
  289. ## Error Handling Best Practices
  290. ### Check Cook State Before Reading Geometry
  291. ```python
  292. # 1. Check cook state first
  293. node_info = get_node_info(
  294. node_path,
  295. include_errors=True,
  296. force_cook=True
  297. )
  298. cook_state = node_info["cook_info"]["cook_state"]
  299. # 2. Handle different states
  300. if cook_state == "error":
  301. # Examine errors
  302. errors = node_info["cook_info"]["errors"]
  303. for err in errors:
  304. print(f"Error: {err['message']}")
  305. # Fix errors...
  306. elif cook_state == "cooked":
  307. # Safe to access geometry
  308. geo = get_geo_summary(node_path)
  309. ```
  310. ### Validate Parameter Types
  311. ```python
  312. # Always check parameter schema before setting
  313. schema = get_parameter_schema(node_path, parm_name="rad")
  314. param = schema["parameters"][0]
  315. if param["type"] == "vector":
  316. # Use list/tuple for vector parameters
  317. set_parameter(node_path, "rad", [5.0, 5.0, 5.0])
  318. else:
  319. # Use scalar for single parameters
  320. set_parameter(node_path, "rad", 5.0)
  321. ```
  322. ### Handle Connection Errors
  323. ```python
  324. # Connection validation
  325. result = connect_nodes(src_path, dst_path)
  326. if result["status"] == "error":
  327. if "incompatible" in result["message"].lower():
  328. # Different node categories (e.g., SOP vs OBJ)
  329. print("Can't connect nodes of different types")
  330. elif "not found" in result["message"].lower():
  331. # Node doesn't exist
  332. print("Source or destination node not found")
  333. ```
  334. ### Debugging with Error Introspection
  335. ```python
  336. # Use include_errors=True to diagnose issues
  337. node_info = get_node_info(
  338. node_path,
  339. include_errors=True,
  340. force_cook=True
  341. )
  342. cook_info = node_info["cook_info"]
  343. # Check for errors
  344. if cook_info["errors"]:
  345. print(f"Node has {len(cook_info['errors'])} errors:")
  346. for error in cook_info["errors"]:
  347. print(f" - {error['message']}")
  348. # Check for warnings
  349. if cook_info["warnings"]:
  350. print(f"Node has {len(cook_info['warnings'])} warnings:")
  351. for warning in cook_info["warnings"]:
  352. print(f" - {warning['message']}")
  353. ```
  354. ## Example Workflows
  355. Complete working examples are available in the `examples/` directory:
  356. - **`build_from_scratch.py`** - Build sphere → xform → color → OUT from scratch
  357. - **`augment_existing_scene.py`** - Insert mountain between grid → noise
  358. - **`parameter_workflow.py`** - Discover → set → verify parameters
  359. - **`error_handling.py`** - Detect → fix → verify errors
  360. Run examples:
  361. ```bash
  362. cd examples
  363. python build_from_scratch.py
  364. python augment_existing_scene.py
  365. python parameter_workflow.py
  366. python error_handling.py
  367. ```
  368. ## Usage Examples
  369. ### With Claude/Cursor
  370. Add to your MCP client configuration:
  371. ```json
  372. {
  373. "mcpServers": {
  374. "houdini": {
  375. "url": "http://localhost:3055"
  376. }
  377. }
  378. }
  379. ```
  380. ### With Letta
  381. Add as an MCP server in Letta's configuration to give agents Houdini control.
  382. ### Example Prompts
  383. - "Create a sphere → transform → color → OUT network"
  384. - "Insert a mountain node between the grid and noise"
  385. - "Discover what parameters are available on the sphere node"
  386. - "Check if the noise node has any cook errors"
  387. - "Set the sphere radius to 3.0 using the parameter schema"
  388. ## Development
  389. ```bash
  390. # Install dev dependencies
  391. pip install -r requirements.txt pytest
  392. # Run tests
  393. pytest tests/
  394. # Run server locally
  395. python -m houdini_mcp
  396. ```
  397. ## Troubleshooting
  398. ### Connection refused
  399. - Verify Houdini is running with hrpyc server started
  400. - Check firewall allows port 18811
  401. - Verify HOUDINI_HOST is correct
  402. ### Authentication errors
  403. - hrpyc uses no authentication by default
  404. - Ensure you're on a trusted network
  405. - The plugin refuses to bind a non-loopback address unless you explicitly opt
  406. in (`HOUDINI_RPC_TRUSTED_NETWORK=1`) or set a shared secret
  407. (`HOUDINI_RPC_TOKEN`). See [docs/remote-listener.md](docs/remote-listener.md)
  408. for the full security model and its limitations.
  409. ## Project Structure
  410. ```
  411. houdini_mcp/
  412. ├── server.py # FastMCP server with 43 tool wrappers
  413. ├── connection.py # RPyC connection with retry/backoff
  414. └── tools/ # Modular tool implementations
  415. ├── _common.py # Shared utilities, error handling
  416. ├── cache.py # Node type caching with TTL
  417. ├── code.py # Python/HScript execution
  418. ├── errors.py # Error node detection
  419. ├── geometry.py # Geometry introspection
  420. ├── help.py # Houdini help access
  421. ├── hscript.py # HScript command execution
  422. ├── layout.py # Node layout tools
  423. ├── materials.py # Material creation/assignment
  424. ├── nodes.py # Node CRUD operations
  425. ├── pane_screenshot.py # Pane capture tools
  426. ├── parameters.py # Parameter get/set
  427. ├── rendering.py # Viewport/Karma rendering
  428. ├── scene.py # Scene management
  429. ├── summarization.py # AI response summarization
  430. └── wiring.py # Node connection tools
  431. houdini_plugin/ # Houdini plugin for stdio mode
  432. ├── python/houdini_mcp_plugin/
  433. ├── toolbar/ # Shelf tools
  434. └── houdini_mcp.json # Package descriptor
  435. tests/ # 418 tests (406 passing)
  436. docs/ # Implementation documentation
  437. examples/ # Working example scripts
  438. ```
  439. ## Credits
  440. - Based on hrpyc integration patterns from [OpenWebUI Houdini Pipeline](https://github.com/oculairmedia/Houdinipipeline)
  441. - Inspired by [capoomgit/houdini-mcp](https://github.com/capoomgit/houdini-mcp)
  442. ## License
  443. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.