Codex Houdini MCP

Control SideFX Houdini from Codex through MCP.

This project packages the setup that lets you type natural language in Codex and create Houdini nodes in the currently visible Houdini GUI scene.

Codex -> MCP server -> Houdini GUI command server -> hou API

What It Includes

Codex plugin manifest: .codex-plugin/plugin.json
Codex skill: skills/houdini-mcp/SKILL.md
MCP server: mcp/houdini/server.py
Houdini GUI command server: mcp/houdini/houdini_command_server.py
Houdini startup hook installer: scripts/install_houdini_gui_hook.py
License diagnostics: scripts/check_sidefx_license_services.sh

Requirements

macOS
SideFX Houdini 21.x
A valid Houdini license, including Apprentice
Python 3.10+, preferably Python 3.11
Codex with MCP support

Install

Clone the repo:

git clone https://github.com/liying/codex-houdini-mcp.git
cd codex-houdini-mcp

Create a Python environment:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install "mcp[cli]"

Install the Houdini GUI startup hook:

python scripts/install_houdini_gui_hook.py --houdini-version 21.0 --project "$PWD"

Restart Houdini. Then verify that the GUI command server is listening:

lsof -nP -iTCP:8765 -sTCP:LISTEN

The process should be houdini or houdinifx, not hython.

Codex MCP Config

Add this to ~/.codex/config.toml, adjusting paths:

[mcp_servers.houdini]
command = "/absolute/path/to/codex-houdini-mcp/.venv/bin/python"
args = ["/absolute/path/to/codex-houdini-mcp/mcp/houdini/server.py"]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.houdini.env]
HOUDINI_MCP_MODE = "http"
HOUDINI_COMMAND_URL = "http://127.0.0.1:8765"

Restart Codex after changing MCP config.

Tools

create_box(size, name)
create_sphere(radius, name)
create_emissive_material(name, color, intensity)
create_black_hole_material(name)
assign_material(node_path, material_path)
create_camera(name, position, target, focal)
frame_object(node_path, camera_name, distance_scale, height_scale, focal)
create_galaxy(star_count, arms, radius, name)
create_space_environment(star_count, radius, name)
inspect_geometry(path)
list_created_nodes()
clear_scene()
save_hip(path)

First Test

Ask Codex:

Use Houdini MCP to clear the scene, create a radius 3 sphere, then list scene nodes.

For a richer test:

Use Houdini MCP to create a deep-space environment, a 5-arm spiral galaxy, emissive materials, a framed camera, then save the .hip file.

License Troubleshooting

Houdini licensing needs local services:

hserver: TCP 1714
sesinetd: TCP 1715

Run:

scripts/check_sidefx_license_services.sh

If localhost:1715 fails, repair or start sesinetd before trying to activate a license.

Safety

This project intentionally exposes fixed Houdini tools instead of arbitrary Python execution. Keep it that way for shared/public use.

MCP Servers