# Houdini MCP

<!-- mcp-name: io.github.JTCHE/houdini-mcp -->

<img src="https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/public/cover.png" alt="An illustration titled &quot;Houdini MCP&quot;, showing three agent platforms linked to the NodebookMD icon" />


  <a href="https://pypi.org/project/houdini-mcp-server/"><img src="https://img.shields.io/pypi/v/houdini-mcp-server?color=blue" alt="PyPI Version"/></a>
  <a href="https://github.com/JTCHE/houdini-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/JTCHE/houdini-mcp?color=blue" alt="License: MIT"/></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"/></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP Compatible"/></a>
  <a href="https://www.sidefx.com/"><img src="https://img.shields.io/badge/Houdini-20.5%20%7C%2021.0%20%7C%2022.0-orange" alt="Houdini 20.5, 21.0 and 22.0"/></a>


Connect SideFX Houdini to Claude, Codex, Gemini, Cursor, opencode or pi.

This MCP provides **Full Markdown Documentation** and **Viewport Screenshots** support to your agents of choice, enabling strong feedback loops and autonomous workflows.

## Install

**Windows**

```powershell
powershell -c "irm https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.bat -OutFile bootstrap.bat; .\bootstrap.bat"
```

**macOS / Linux**

```bash
curl -sSL https://raw.githubusercontent.com/JTCHE/houdini-mcp/main/bootstrap.sh | bash
```

**uv**

```bash
uv tool install houdini-mcp-server && houdinimcp-install
```

The installer adds the plugin to Houdini and the server to your AI clients of choice. Restart both.\
pi also needs `pi install npm:pi-mcp-adapter`.

**Claude plugin**

This repository is also a Claude plugin, for Claude Code and for Cowork on your computer. It needs [uv](https://docs.astral.sh/uv/).
The plugin starts a headless Houdini without setup. To connect the Houdini that you have open, ask Claude to run the `houdini-setup` skill.

<details>
<summary><b>What the plugin runs</b></summary>

- `uv run --frozen` builds an environment from `uv.lock` in the plugin folder, then starts the MCP server from this repository.
- The server talks to Houdini on `localhost` only. It starts `hython`, or `houdini` on request, from your Houdini install, and `ffmpeg` to encode a flipbook movie.
- `docs` reads the documentation out of your Houdini install with [houdinimd-docs](https://pypi.org/project/houdinimd-docs/). It sends nothing over the network.
- `houdini-setup` writes the HoudiniMCP package into your Houdini preferences folder, after you approve it.
- No tool sends data to a remote service. `execute` runs any Python that Claude writes in your Houdini session.

</details>

## Tools

| | |
|---|---|
| **Read** | `scene_overview` `node_inspect` `geometry_inspect` `stage_inspect` `select` `console` |
| **Edit** | `node_edit` `parm_set` `connect` `hda` `batch` |
| **Run** | `cook` `render` `pdg` `playbar` `scene_file` |
| **See** | `capture`: the viewport, a camera, four views or a flipbook |
| **Code** | `execute`: Python, HScript, expressions, VEX check |
| **Docs** | `docs`: the Houdini documentation of your build, offline, from [houdinimd-docs](https://pypi.org/project/houdinimd-docs/) |
| **Session** | `session`: status; starts Houdini headless or with its window |

No Houdini open? The server starts a headless `hython`.

`batch` builds a whole network in one call, and it is all or nothing: a failed
step undoes the steps before it. A build that works comes back with the cooked
point and primitive counts, and the nodes with errors.

> **Warning:** `execute` runs any Python in Houdini. Save your work.

<details>
<summary><b>Troubleshooting</b></summary>

| Problem | Fix |
|---|---|
| No Houdini listens for the bridge | Start Houdini, or click **Toggle MCP Server** on the HoudiniMCP shelf. |
| No HoudiniMCP shelf | Restart Houdini. `houdinimcp-install --list` shows where the plugin went. |
| Houdini started from Git Bash has no plugin | Git Bash sets `HOME`. Set the user variable `HOUDINI_USER_PREF_DIR` to `%USERPROFILE%\Documents\houdini__HVER__`. |
| `capture` says there is no viewport | The session is headless. Call `session` with `action="start_gui"`. |
| You must have a fixed port | Set `HOUDINIMCP_PORT` for Houdini and for the bridge. Without it, the plugin takes a free port from the operating system and tells the bridge which one. |

</details>

<details>
<summary><b>For agents and scripts</b></summary>

Without a terminal, the installer asks nothing and takes the defaults.

```bash
houdinimcp-install --list          # Houdini installs and clients found, as JSON
houdinimcp-install --yes --json    # newest Houdini, every client found; JSON report
houdinimcp-install --houdini-version 22.0 --harness claude-code --yes
houdinimcp-install --dry-run --yes # change nothing
houdinimcp-install --uninstall     # remove the plugin and every client entry
```

Flags: `--houdini-version none` skips the plugin, `--prefs-dir PATH` names the
prefs folder, `--harness none|all|KEY` (repeatable), `--quiet-start` stops the
first-launch dialogs. The bootstrap scripts pass every flag through.

Manual client setup: run `houdinimcp-bridge` with no arguments.
`claude mcp add --transport stdio houdini -- houdinimcp-bridge` for Claude Code.

From a clone: `uv run python -m bridge.onboarding.install`.

Layout: `src/houdinimcp/` is the plugin, a TCP server inside Houdini on
`localhost:9877`. `src/bridge/` is the MCP server and the installer. Messages
are JSON with a 4-byte length prefix. `HOUDINIMCP_NO_HEADLESS=1` stops the
headless start. Read [AGENTS.md](AGENTS.md) before you change code.

</details>

## Credits

Built on [blender-mcp](https://github.com/ahujasid/blender-mcp),
[capoomgit/houdini-mcp](https://github.com/capoomgit/houdini-mcp),
[eetumartola/houdini-mcp](https://github.com/eetumartola/houdini-mcp),
[Houdini21MCP](https://github.com/orrzxz/Houdini21MCP) and
[fxhoudinimcp](https://github.com/healkeiser/fxhoudinimcp). MIT licensed.

<sub>Not affiliated with SideFX. Houdini and SideFX are trademarks of SideFX Software Inc.</sub>