opera-houdini-mcp · Houdini MCP 的 Opera Fork

本仓库是 capoomgit/houdini-mcp 的独立 fork，面向 CsrLib-Houdini 的生产使用。MIT 协议完整保留，Capoom 2025 原版权声明与致谢保留在最末。

上游基线：capoomgit/houdini-mcp @ de4fd93（2026-07-17 同步）。 同步策略：以 cherry-pick 为主，禁止 merge（避免污染 opera 自己的提交图）。

关于本 Fork

opera-houdini-mcp 是为 CsrLib-Houdini 工作流量身定制的 Houdini MCP 服务端。它在功能上与上游完全兼容，但额外提供：

• Tier 1 工具集（13 个独立模块，详见 Tier 1 工具清单）： 场景 CRUD、节点发现、图编辑增强、get_node_info 增强、材质、几何摘要、错误节点扫描（含 warnings）、execute_code 安全护栏、pane 截图与 base64 渲染、SideFX 在线文档查询、连接诊断、缓存管理、基础设施（_common.py）。

• execute_code 安全模型：三档 policy（read-only / normal / privileged）+ dangerous / heavy / mutation 三套模式黑名单（正则 + AST 别名双检）+ 双开关 bypass（请求端 allow_dangerous 配服务端环境变量 HOUDINI_MCP_ALLOW_BYPASS）+ 结构化 audit。

• 零新增 pip 依赖：get_houdini_help 用 stdlib html.parser 替代 beautifulsoup4，仍然保持 mcp[cli]==1.12.2 + requests + python-dotenv 三件套。

老用户升级路径：在 CsrLib-Houdini 仓库根目录执行 git submodule update --remote external/houdinimcp && git submodule sync，无需重装 env、无需改动 AI 工具 JSON。

Related MCP server: maya-mcp-server

Table of Contents

1. Requirements

2. Houdini MCP Plugin Installation

   1. Folder Layout

   2. Shelf Tool (Optional)

   3. Packages Integration (Optional)

3. Installing the mcp Python Package

   1. Using uv on Windows

   2. Using pip Directly

4. Bridging Script and Claude for Desktop

   1. The Bridging Script

   2. Telling Claude Desktop to Use Your Script

5. Testing & Usage

6. Tier 1 工具清单

7. execute_code 安全模型

8. Troubleshooting

9. Acknowledgement

Requirements

• SideFX Houdini

• uv

• Claude Desktop (latest version)

1. Houdini MCP Plugin Installation

1.1 Folder Layout

Create a folder in your Houdini scripts directory: C:/Users/YourUserName/Documents/houdini19.5/scripts/python/houdinimcp/

Inside houdinimcp/, place:

• __init__.py – handles plugin initialization (start/stop server)

• server.py – defines the HoudiniMCPServer (listening on port 9876)

• houdini_mcp_server.py – optional bridging script (some prefer a separate location)

• pyproject.toml

(If you prefer, houdini_mcp_server.py can live elsewhere. As long as you know its path for running with uv.)

1.2 Shelf Tool

create a Shelf Tool to toggle the server in Houdini:

1. Right-click a shelf → "New Shelf..."

   Name it "MCP" or something similar

2. Right-click again → "New Tool..." Name: "Toggle MCP Server" Label: "MCP"

3. Under Script, insert something like:

   import hou
   import houdinimcp

   if hasattr(hou.session, "houdinimcp_server") and hou.session.houdinimcp_server:
       houdinimcp.stop_server()
       hou.ui.displayMessage("Houdini MCP Server stopped")
   else:
       houdinimcp.start_server()
       hou.ui.displayMessage("Houdini MCP Server started on localhost:9876")

1.3 Packages Integration

If you want Houdini to auto-load your plugin at startup, create a package file named houdinimcp.json in the Houdini packages folder (e.g. C:/Users/YourUserName/Documents/houdini19.5/packages/):

{
  "path": "$HOME/houdini19.5/scripts/python/houdinimcp",
  "load_package_once": true,
  "version": "0.1",
  "env": [
    {
      "PYTHONPATH": "$PYTHONPATH;$HOME/houdini19.5/scripts/python"
    }
  ]
}

2 Using uv on Windows

  # 1) Install uv
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

  # 2) add uv to your PATH (depends on the user instructions) from cmd
  set Path=C:\Users\<YourUserName>\.local\bin;%Path%

  # 3) In a uv project or the plugin directory
  cd C:/Users/<YourUserName>/Documents/houdini19.5/scripts/python/houdinimcp/
  uv add "mcp[cli]"

  # 4) Verify
  uv run python -c "import mcp.server.fastmcp; print('MCP is installed!')"

3 Telling Claude for Desktop to Use Your Script

Go to File > Settings > Developer > Edit Config > Open or create: claude_desktop_config.json

Add an entry:

{
  "mcpServers": {
    "houdini": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "C:/Users/<YourUserName>/Documents/houdini19.5/scripts/python/houdinimcp/houdini_mcp_server.py"
      ]
    }
  }
}

if uv run was successful and claude failed to load mcp, make sure claude is using the same python version, use:

  python -c "import sys; print(sys.executable)"

to find python, and replace "python" with the path you got.

4 Use Cursor

Go to Settings > MCP > add new MCP server add the same entry in claude_desktop_config.json you might need to stop claude and restart houdini and the server

5 OPUS integration

OPUS provide a large set of furniture and environmental procedural assets. you will need a Rapid API key to log in. Create an account at: RapidAPI Subscribe to OPUS API at: OPUS API Subscribe Get your Rapid API key at OPUS API copy urls.env.example to urls.env and add your key (the file is gitignored). OPUS integration is optional — without a key the server still starts, only the OPUS tools are disabled.

Tier 1 工具清单

以下工具以独立 PR 形式陆续合入。每次合入后会在 CHANGELOG.md 追加记录。本节列出最终交付时的目标清单。

execute_code 安全模型

双开关原则：任何 dangerous / heavy / privileged 操作都需要「请求端参数 + 服务端环境变量」同时开启。服务端不开环境变量，再多客户端请求也无效。

Audit：每次 execute_code 调用都会在响应里附 _audit 块（policy / dangerous_hits / heavy_hits / mutation_hits / bypass_used / elapsed_ms / undo_group / exception）。

超时：执行超时不会自动 hou.undos.performUndo()，避免误回滚正常操作。客户端需根据 _audit.elapsed_ms 自行决定。

Troubleshooting

Acknowledgement

Houdini-MCP was built following blender-mcp. We thank them for the contribution.

opera-houdini-mcp 是 capoomgit/houdini-mcp 的独立 fork，遵循 MIT 协议，原版权归 Capoom 2025 所有。本 fork 在 CsrLib-Houdini 工作流下使用，提交通过 cherry-pick 而非 merge 同步上游。

License

本仓库全部代码沿用上游 MIT License。opera-houdini-mcp 本身的改动部分同样以 MIT 协议发布。