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.