[TA #2] Houdini MCP 연결 — Houdini 19.5를 Claude Code에 붙이기

■ 목표

Houdini를 Claude Code에서 직접 조작하게 만든다. 노드 만들고, 파라미터 바꾸고, VEX 랭글 쓰고, 지오메트리를 조회하는 걸 채팅으로 시키는 구조다. 쓴 서버는 capoomgit/houdini-mcp. 로컬 Houdini는 19.5.368이라 최신 버전 기준으로 만들어진 코드가 여기서 도는지가 관건이었다.

Goal — Drive Houdini from Claude Code: create nodes, set parameters, write VEX wrangles, inspect geometry, all from chat. The server is capoomgit/houdini-mcp. My local Houdini is 19.5.368, so the real question was whether code written against newer builds runs here.

■ 환경

OS	Windows 11
Houdini	19.5.368 (내장 Python 3.9.10, PySide2 5.15.2)
시스템 Python	3.12.10
Claude Code	2.1.220
houdini-mcp	commit de4fd93 (2026-06-11)
uv	0.12.17 (이번에 설치)

Environment — Windows 11, Houdini 19.5.368 (bundled Python 3.9.10 / PySide2 5.15.2), system Python 3.12.10, Claude Code 2.1.220, houdini-mcp at commit de4fd93, uv 0.12.17 installed for this.

■ 구조 — 프로세스가 둘이다

설치 전에 이걸 먼저 이해해야 뒤의 이슈가 전부 설명된다.

Claude Code ──stdio──> houdini_mcp_server.py (시스템 Python 3.12, FastMCP)
                              │ TCP 127.0.0.1:9876
                              ▼
                     Houdini GUI 프로세스
                     └ houdinimcp/server.py (Houdini 내장 Python 3.9, QTimer 폴링)
                       └ hou API

• 브릿지(houdini_mcp_server.py)는 Claude Code가 띄우는 별도 프로세스. Python 3.12 이상이 필요하고 mcp 패키지를 쓴다.
• 플러그인(server.py)은 Houdini 안에서 돈다. Houdini 내장 Python 3.9로 실행되고, mcp 패키지가 필요 없다. 소켓만 연다.
• 둘은 Python도 패키지도 공유하지 않는다. 그래서 hython에 mcp를 설치할 필요가 없고, 설치하면 오히려 꼬인다(뒤의 이슈 참고).

Architecture — Two processes. The bridge (houdini_mcp_server.py) is spawned by Claude Code, needs Python ≥3.12 and the mcp package. The plugin (server.py) runs inside Houdini on its bundled Python 3.9 and only opens a socket — it never needs mcp. They share neither interpreter nor packages, which explains most of the issues below.

■ 설치 방법

경로 약속: REPO = 저장소 clone 위치, PREF = C:\Users\<이름>\Documents\houdini19.5.

1. 저장소 clone

git clone https://github.com/capoomgit/houdini-mcp REPO

2. uv 설치 (README 표준 경로. pip venv로도 되지만 lock 재현이 편해서 uv를 택했다)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 설치 위치: C:\Users\<이름>\.local\bin\uv.exe  (PATH에 자동 등록되지 않음)

3. 브릿지 의존성 설치 — uv.lock에 mcp 1.4.1이 고정돼 있다. 이 버전이어야 한다(이슈 1).

cd REPO
uv sync --python 3.12
uv run python -c "import mcp.server.fastmcp; from importlib.metadata import version; print(version('mcp'))"
# → 1.4.1

4. Houdini 쪽 배치 — README는 PREF\scripts\python\houdinimcp에 넣으라고 하는데, 19.5에서 그 경로는 기본 sys.path에 없다(이슈 2). Houdini 표준 경로인 python3.9libs에 junction으로 연결했다. 복사 대신 링크라서 git pull이 그대로 반영된다.

mkdir "PREF\python3.9libs"
cmd /c mklink /J "PREF\python3.9libs\houdinimcp" "REPO"
"C:\Program Files\Side Effects Software\Houdini 19.5.368\bin\hython.exe" -c "import houdinimcp; print(houdinimcp.__file__)"
# → PREF\python3.9libs\houdinimcp\__init__.py 이면 성공

5. 셸프 파일 — GUI에서 버튼을 손으로 만드는 대신 PREF\toolbar\houdinimcp.shelf를 파일로 넣었다. Start MCP / Stop MCP 두 개. 스크립트 본문은 저장소의 shelf_tool_start_mcp.py / shelf_tool_stop_mcp.py에 import hou 한 줄만 붙인 것이다.

<?xml version="1.0" encoding="UTF-8"?>
<shelfDocument>
  <tool name="houdinimcp_start" label="Start MCP" icon="MISC_python">
    <script scriptType="python"><![CDATA[
import hou
import houdinimcp
if houdinimcp.is_server_running():
    print("already running")
else:
    houdinimcp.start_server()
]]></script>
  </tool>
  <tool name="houdinimcp_stop" label="Stop MCP" icon="MISC_python">
    <script scriptType="python"><![CDATA[
import hou
import houdinimcp
houdinimcp.stop_server()
]]></script>
  </tool>
  <toolshelf name="houdinimcp" label="Houdini MCP">
    <memberTool name="houdinimcp_start"/>
    <memberTool name="houdinimcp_stop"/>
  </toolshelf>
</shelfDocument>

Houdini를 열고 셸프 탭 줄 오른쪽 끝 + → Shelves → Houdini MCP 체크하면 탭이 생긴다.

6. Claude Code 등록 — project 스코프로 넣으면 작업 폴더의 .mcp.json에 기록된다. uv가 PATH에 없으므로 절대 경로.

claude mcp add -s project houdini -- C:\Users\<이름>\.local\bin\uv.exe run --directory REPO python REPO\houdini_mcp_server.py

생성된 .mcp.json:

{
  "mcpServers": {
    "houdini": {
      "type": "stdio",
      "command": "C:\\Users\\<이름>\\.local\\bin\\uv.exe",
      "args": ["run", "--directory", "REPO", "python", "REPO\\houdini_mcp_server.py"],
      "env": {}
    }
  }
}

시스템에 손댄 곳은 이 셋뿐이다: uv 설치, PREF 아래 junction·셸프 파일, .mcp.json. 각각 지우면 원복된다.

Install — (1) clone the repo, (2) install uv, (3) uv sync so the lock pins mcp 1.4.1, (4) junction the repo into PREF\python3.9libs\houdinimcp (the README's scripts\python path is not on 19.5's default sys.path), (5) drop a .shelf file with Start/Stop tools into PREF\toolbar, (6) claude mcp add -s project with the absolute path to uv.exe. Only three things touch the system: uv, the junction + shelf file, and .mcp.json.

■ 테스트 진행 순서

"Houdini 켜고 눌러본다"를 맨 마지막에 뒀다. 그 전에 사람 손 없이 검증할 수 있는 층을 아래서부터 쌓았다.

0층. 문법·임포트 — Houdini를 켜지 않고

플러그인이 Houdini 내장 Python 3.9에서 돌아야 한다. 최신 버전 기준으로 짠 코드에 3.10 이상 문법(match, X | Y)이 섞여 있으면 여기서 죽는다.

"C:\...\Houdini 19.5.368\python39\python.exe" -m py_compile REPO\server.py   # 통과
hython -c "from PySide2 import QtCore; import numpy, requests"                # 통과

1층. 브릿지 단독 — Houdini 꺼진 상태

등록한 명령 그대로 MCP 클라이언트로 띄워서 핸드셰이크·툴 목록을 확인했다. Houdini가 없으니 툴 호출은 실패해야 하고, 그 실패 메시지가 사람이 읽을 만한지를 봤다.

server: HoudiniMCP 1.4.1
tools: 25 ['get_scene_info', 'create_node', 'execute_houdini_code', ...]
get_scene_info: Could not connect to Houdini on 127.0.0.1:9876. Is the plugin running?

2층. 헤드리스 통합 테스트 — GUI 없이 진짜 hou

저장소에 tests/headless_host.py가 있다. hython으로 server.py를 띄우되 QTimer 대신 루프로 소켓을 폴링한다. 그 위에 tests/test_tools.py를 돌리면 노드 생성·파라미터·VEX 컴파일·지오메트리 조회·연결 교체까지 실제 hou API로 검증된다.

hython REPO\tests\headless_host.py 19878        # 터미널 1
uv run python REPO\tests\test_tools.py 19878    # 터미널 2
# → ALL 15 TEST GROUPS PASSED

19.5.368에서 15개 그룹 전부 통과. 여기까지 왔으면 GUI에서 안 될 이유는 셸프 로딩 정도만 남는다.

3층. 실제 GUI

1. Houdini 실행 → 셸프 Start MCP → 상태바 HoudiniMCP server started on 127.0.0.1:9876
2. netstat -ano | findstr :9876 → LISTENING
3. 브릿지 경유로 /obj/mcp_test(geo) → box1 생성 → get_geometry_info가 점 8·프림 6·바운딩박스 1×1×1 응답
4. 네트워크 뷰와 뷰포트에서 눈으로 확인 → delete_node로 정리 → /obj 비어 있음 확인
5. Stop MCP → 포트 닫힘 → 툴 호출 시 1층과 같은 연결 오류 메시지

[스크린샷 ① — Start MCP 클릭 후 상태바. 이 줄을 지우고 Blogger 이미지 버튼으로 업로드]

[스크린샷 ② — 네트워크 뷰의 mcp_test / box1. 이 줄을 지우고 업로드]

Test order — Bottom-up, with the GUI last. (0) py_compile the plugin with Houdini's own Python 3.9 and import PySide2/numpy/requests in hython. (1) Launch the bridge alone as an MCP client: handshake, 25 tools, and a readable "Is the plugin running?" error with Houdini off. (2) The repo's tests/headless_host.py hosts server.py in hython without Qt; tests/test_tools.py against it passed all 15 groups on 19.5.368. (3) Real GUI: Start MCP → port listening → create geo+box through the bridge → eyeball it → delete → Stop MCP → clean connection error.

■ 이슈와 해결

1. mcp 2.x에서 브릿지가 안 뜬다 — 가장 큰 함정

브릿지는 from mcp.server.fastmcp import FastMCP를 쓴다. PyPI 최신 mcp(2.0, 2026-08~)는 이 모듈을 제거했고, 임포트하면 마이그레이션 가이드 에러가 난다. 저장소 uv.lock은 1.4.1을 고정하고 있어서 uv sync를 쓰면 안전하다. pip로 깔 거면 "mcp[cli]<2"로 고정해야 한다. README에는 이 얘기가 없다.

2. README의 scripts/python 경로가 19.5 기본 sys.path에 없다

hython에서 sys.path를 찍어보면 PREF\scripts\python은 없고 python3.9libs가 표준이다. SideFX Labs처럼 패키지 JSON으로 HOUDINI_PATH에 폴더를 추가한 경우에만 그 아래 scripts/python이 잡힌다. 그래서 python3.9libs\houdinimcp로 갔다.

덤으로 하나 더. Git Bash에서 hython을 돌리면 HOME이 C:\Users\<이름>으로 잡혀서 프리퍼런스 경로가 C:\Users\<이름>\houdini19.5로 바뀐다. 실제 GUI가 쓰는 Documents\houdini19.5와 다르다. 경로 검증은 PowerShell에서 해야 맞는 답이 나온다.

3. README §1.3 "패키지 JSON으로 자동 로드"는 동작하지 않는다 (이슈 #13)

Houdini 패키지 JSON은 경로를 추가할 뿐 Python 모듈을 임포트하지 않는다. 자동 시작을 원하면 PREF\scripts\456.py에 import houdinimcp; houdinimcp.start_server()를 넣는 게 맞는 방법이다. 이번엔 셸프 수동 시작으로 두고 자동 시작은 보류했다.

4. 서버가 단일 클라이언트다 (이슈 #14)

첫 클라이언트가 붙어 있으면 두 번째는 accept되지 않고 무한 대기한다. Claude Desktop과 Claude Code에 둘 다 등록하면 한쪽이 먹통이 된다. Claude Code 하나만 등록했다. (같은 이유로 blender-mcp도 9876을 쓰므로 동시 실행 금지.)

5. hython으로 브릿지를 돌리려 하면 안 된다 (이슈 #9)

이슈에 "hython에 mcp를 pip install하고 hython으로 브릿지를 실행하라"는 답이 달려 있는데, 이건 오답이다. hython은 site-packages-forced가 앞에 끼어들어 일반 패키지 임포트를 깨뜨린다. 브릿지는 시스템 Python 3.12로, 플러그인은 Houdini 안에서 — 구조 그림대로 분리하면 hython엔 아무것도 설치할 게 없다.

6. 작은 것들

• uv 설치 후 PATH에 자동 등록되지 않는다. .mcp.json에는 uv.exe 절대 경로를 넣었다. Windows에서 spawn uvx ENOENT가 나오는 흔한 원인.
• project 스코프 .mcp.json은 다음 세션 시작 때 승인 프롬프트가 한 번 뜬다. 이미 열려 있는 세션에는 반영되지 않는다.
• langchain, langchain-classic 의존성은 OPUS(유료 에셋 API) 전용이다. 없어도 경고만 내고 뜬다. uv sync는 lock대로 다 깔지만 실제로 안 쓴다.

Issues — (1) mcp 2.x removed mcp.server.fastmcp; the lock pins 1.4.1, pin <2 if you use pip. (2) The README's scripts\python isn't on 19.5's default sys.path — use python3.9libs. Also, hython under Git Bash reports the wrong pref dir because HOME is overridden; verify from PowerShell. (3) README §1.3's package JSON doesn't auto-import (issue #13); use a 456.py hook if you want autostart. (4) Single-client server (issue #14): register only one MCP client. (5) Don't run the bridge under hython (issue #9); site-packages-forced breaks imports. (6) uv isn't added to PATH — use the absolute path; a project-scope .mcp.json needs approval in a fresh session; the langchain deps are OPUS-only.

■ 배운 것 / 막힌 것

• 프로세스가 둘이라는 그림 하나로 이슈 대부분이 설명된다. hython에 뭘 깔아야 하나 헤맨 사람들(이슈 #9)은 그 그림이 없었다.
• GUI는 마지막에. py_compile → 브릿지 단독 → 헤드리스 통합 테스트 순서로 쌓으니 GUI에서 사람이 할 일이 버튼 두 번 누르는 걸로 줄었다. 저장소에 headless_host.py가 있다는 걸 먼저 발견한 게 컸다.
• lock 파일은 읽어야 한다. pyproject.toml의 mcp[cli]>=1.4.1만 보면 최신을 깔게 되고, 그러면 죽는다. lock이 1.4.1을 잡고 있는 건 우연이 아니었다.
• 미검증: 렌더 툴 3종(render_single_view 등)은 헤드리스 테스트 범위 밖이라 19.5 뷰포트 API에서 도는지 아직 모른다.
• execute_houdini_code는 Houdini 프로세스 안에서 임의 Python을 실행한다. 파일 삭제도 된다. 이 툴 호출은 사람이 확인하고 넘기는 규칙을 그대로 적용하기로 했다.

Learned / Stuck — One diagram (two processes) explains nearly every issue. Keep the GUI for last: compile → bridge alone → headless integration tests left only two button clicks for a human. Read the lock file, not just pyproject.toml. Unverified: the three render tools. execute_houdini_code runs arbitrary Python inside Houdini, so it stays behind a human-confirmation rule.

Sources

• github.com/capoomgit/houdini-mcp — 저장소, 이슈 #9 #13 #14
• MCP Python SDK releases — v2.0.1 / v2.1.1 릴리스 노트 (mcp.server.fastmcp 제거)
• uv