使用说明

项目简介

Houdini MCP 是一个 MCP 服务器的实现，它允许大型语言模型（LLM），如 Claude，通过标准的 Model Context Protocol (MCP) 控制 SideFX Houdini。它包含一个 Houdini 插件和一个桥接脚本，共同实现 Claude 对 Houdini 的远程控制，并扩展了通过 OPUS API 生成 3D 资产的功能。

主要功能点

Houdini 远程控制: 允许 Claude 通过 MCP 协议与 Houdini 交互，创建、修改和删除 Houdini 节点，执行 Python 代码，设置材质等。
OPUS API 集成: 集成了 OPUS API，允许 Claude 通过自然语言指令生成和导入 3D 模型资产。
资源管理 (Resources): 通过 'get_scene_info' 和 'get_node_info' 等工具，向 Claude 提供 Houdini 场景和节点信息，作为上下文资源。
工具注册和执行 (Tools): 提供一系列预定义的工具，例如 'create_node', 'execute_houdini_code', 'opus_create_model', 'opus_import_model_url' 等，允许 Claude 调用 Houdini 的功能和 OPUS API。
会话管理: 通过 Houdini 插件和桥接脚本的配合，管理 Claude 与 Houdini 之间的会话。
多种传输协议支持: 使用标准输入/输出 (stdio) 与 Claude 通信，使用 TCP 与 Houdini 插件通信。

安装步骤

安装 Houdini MCP 插件:
- 在 Houdini 脚本目录中创建 'houdinimcp' 文件夹，例如 'C:/Users/YourUserName/Documents/houdini19.5/scripts/python/houdinimcp/'。
- 将仓库中的 'init.py', 'server.py', 'houdini_mcp_server.py', 'pyproject.toml' 文件复制到 'houdinimcp' 文件夹中。
- （可选）创建 Shelf Tool 以在 Houdini 中切换 MCP 服务器的启动和停止。
- （可选）配置 Packages Integration 以在 Houdini 启动时自动加载插件。
安装 'mcp' Python 包:
- 确保已安装 'uv' 或 'pip'。
- 在 'houdinimcp' 插件目录或 uv 项目中，运行命令安装 'mcp[cli]' 包：
```
uv add "mcp[cli]"
```
  或
```
pip install "mcp[cli]"
```

配置 RapidAPI 密钥 (OPUS 集成):

如果需要使用 OPUS API 功能，请访问 RapidAPI 并订阅 OPUS API。

获取 Rapid API 密钥并将其添加到 'houdini_mcp_server.py' 文件所在目录的 'urls.env' 文件中，文件内容示例如下：

RAPIDAPI_HOST_URL=https://opus5.p.rapidapi.com/
RAPIDAPI_HOST=opus5.p.rapidapi.com
RAPIDAPI_KEY=YOUR_RAPID_API_KEY

服务器配置

要将 Houdini MCP 服务器配置到 MCP 客户端（例如 Claude Desktop 或 Cursor），您需要提供服务器的启动命令和参数。以下是 'claude_desktop_config.json' 的配置示例，适用于 Claude Desktop，其他 MCP 客户端的配置方式类似：

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

配置参数说明:

'"houdini"': 服务器名称，可以自定义。
'"command": "uv"': 启动服务器的命令，这里使用 'uv' 运行 Python 脚本。如果使用系统 Python 或其他虚拟环境，请根据实际情况修改命令。
'"args"': 命令参数列表。
- '"run"': 'uv' 命令的子命令，表示运行。
- '"python"': 指定使用 Python 解释器。
- '"C:/Users/<YourUserName>/Documents/houdini19.5/scripts/python/houdinimcp/houdini_mcp_server.py"': Houdini MCP 桥接脚本的完整路径。请务必替换为您的实际路径。

Cursor 配置:

Cursor 的 MCP 服务器配置与 'claude_desktop_config.json' 类似，您可以在 Cursor 的设置中添加新的 MCP 服务器，并填入相同的配置信息。

基本使用方法

启动 Houdini: 确保 Houdini 软件已启动，并且 Houdini MCP 插件已正确安装并启动（可以通过 Shelf Tool 或 Packages Integration 启动）。
配置 MCP 客户端: 根据 MCP 客户端 (如 Claude Desktop, Cursor) 的指引，配置 MCP 服务器连接，填入上述服务器配置信息。
连接服务器: 在 MCP 客户端中连接到名为 "houdini" (或您自定义的服务器名称) 的 MCP 服务器。
使用自然语言指令控制 Houdini: 在 MCP 客户端中使用自然语言指令，例如：
- "在场景中创建一个红色球体"
- "将节点的颜色改为蓝色"
- "使用 OPUS API 创建一个沙发模型并导入场景"
- "执行 Python 代码，输出当前帧数"

MCP 客户端会将您的自然语言指令转换为 MCP 请求，发送到 Houdini MCP 服务器。服务器解析请求后，会控制 Houdini 或调用 OPUS API 执行相应的操作，并将结果返回给 MCP 客户端。

关键词