Cinema4D MCP — Model Context Protocol (MCP) Server

Cinema4D MCP — Model Context Protocol（MCP）服务

Cinema4D MCP 服务将 Cinema 4D 连接到 Claude，支持通过提示词辅助进行 3D 操作。

目录

• 组件
• 先决条件
• 安装
• 设置
• 使用方法
• Agent 技能
• 开发
• 故障排除与调试
• 文件结构
• 工具命令
• 使用指南 — 实用技巧、提取模式和已知问题

组件

1. C4D 插件：一个套接字服务，用于监听 MCP 服务发送的命令，并在 Cinema 4D 环境中执行这些命令。
2. MCP 服务：一个实现 MCP 协议并提供 Cinema 4D 集成工具的 Python 服务。

先决条件

• Cinema 4D（建议使用 R2024+）
• Python 3.10 或更高版本（用于 MCP 服务组件）

安装

安装此项目，请按以下步骤操作：

克隆代码库

git clone https://github.com/ttiimmaacc/cinema4d-mcp.git
cd cinema4d-mcp

安装 MCP 服务包

pip install -e .

使包装脚本可执行

chmod +x bin/cinema4d-mcp-wrapper

设置

Cinema 4D 插件设置

设置 Cinema 4D 插件，请按以下步骤操作：

1. 复制插件文件：将 c4d_plugin/mcp_server_plugin.pyp 文件复制到 Cinema 4D 的插件文件夹。路径因操作系统而异：

   • macOS：/Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/
   • Windows：C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\

2. 启动套接字服务：

   • 打开 Cinema 4D。
   • 前往 Extensions > Socket Server Plugin
   • 此时应会显示 Socket Server Control 对话框。点击 Start Server。

Claude Desktop 配置

要配置 Claude Desktop，需要修改其配置文件：

1. 打开配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • 或者使用 Claude Desktop 中的 Settings 菜单（Settings > Developer > Edit Config）。

2. 添加 MCP 服务配置： 对于开发中／未发布的服务，添加以下配置：

   "mcpServers": {
     "cinema4d": {
       "command": "python3",
       "args": ["/Users/username/cinema4d-mcp/main.py"]
     }
   }
   

3. 更新配置文件后，重启 Claude Desktop。

{
  "mcpServers": {
    "cinema4d": {
      "command": "cinema4d-mcp-wrapper",
      "args": []
    }
  }
}

使用方法

1. 确保 Cinema 4D 套接字服务正在运行。
2. 打开 Claude Desktop，并在输入框中找到锤子图标 🔨，表示 MCP 工具已可用。
3. 使用可用的工具命令，通过 Claude 与 Cinema 4D 交互。

Agent 技能

如果你使用 Agent 技能，此 MCP 的配套技能由 vladmdgolam/agent-skills 维护。

此技能提供基于原始 MCP 工具的生产实践指导，包括：

• 检查 Redshift 时，何时优先使用 inspect_redshift_materials 而非临时编写 Python
• 何时回退到 execute_python_script 以访问完整的 C4D API
• 运行时或节点空间不可用时当前 Redshift 的限制
• 实用的 MoGraph 提取与调试工作流

测试

命令行测试

要直接从命令行测试 Cinema 4D 套接字服务：

python main.py

你应该会看到确认服务成功启动并连接到 Cinema 4D 的输出。

使用 MCP 测试工具包进行测试

仓库包含一个简单的测试工具包，可用于运行预定义的命令序列：

1. 测试命令文件（tests/mcp_test_harness.jsonl）：以 JSONL 格式包含一系列可按顺序执行的命令。每一行表示一条带参数的 MCP 命令。

2. GUI 测试运行器（tests/mcp_test_harness_gui.py）：一个用于运行测试命令的简单 Tkinter GUI：

   python tests/mcp_test_harness_gui.py
   

   GUI 可用于：

   • 选择 JSONL 测试文件
   • 按顺序运行命令
   • 查看来自 Cinema 4D 的响应

此测试工具包特别适用于：

• 快速测试新命令
• 更新后验证插件功能
• 重新创建复杂场景以进行调试
• 测试与不同 Cinema 4D 版本的兼容性

故障排除与调试

1. 检查日志文件：

   tail -f ~/Library/Logs/Claude/mcp*.log
   

2. 打开 Claude Desktop 后，确认 Cinema 4D 的控制台中显示了连接信息。

3. 直接测试包装脚本：

   cinema4d-mcp-wrapper
   

4. 如果出现找不到 mcp 模块的错误，请在系统范围内安装该模块：

   pip install mcp
   

5. 如需进行高级调试，请使用 MCP Inspector：

   npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp
   

项目文件结构

cinema4d-mcp/
├── .gitignore
├── LICENSE
├── README.md
├── main.py
├── pyproject.toml
├── setup.py
├── bin/
│   └── cinema4d-mcp-wrapper
├── c4d_plugin/
│   └── mcp_server_plugin.pyp
├── src/
│   └── cinema4d_mcp/
│       ├── __init__.py
│       ├── server.py
│       ├── config.py
│       └── utils.py
└── tests/
    ├── test_server.py
    ├── mcp_test_harness.jsonl
    └── mcp_test_harness_gui.py

工具命令

通用场景与执行

• get_scene_info：获取当前 Cinema 4D 场景的摘要信息。✅
• list_objects：列出场景中的所有对象（含层级结构）。✅
• group_objects：将所选对象分组到一个新空对象下。✅
• execute_python：在 Cinema 4D 中执行自定义 Python 代码。✅
• save_scene：将当前 Cinema 4D 项目保存到磁盘。✅
• load_scene：将 .c4d 文件载入场景。✅
• set_keyframe：为对象属性（位置、旋转等）设置关键帧。✅

对象创建与修改

• add_primitive：向场景添加基本体（立方体、球体、圆锥体等）。✅
• modify_object：修改现有对象的变换或属性。✅
• create_abstract_shape：创建有机、非标准的抽象形状。✅

摄像机与动画

• create_camera：向场景添加新摄像机。✅
• animate_camera：沿路径（线性或基于样条）为摄像机添加动画。✅

灯光与材质

• create_light：添加灯光（全向灯、聚光灯等）。✅
• create_material：创建标准 Cinema 4D 材质。✅
• apply_material：将材质应用于目标对象。✅
• apply_shader：生成并应用风格化或程序化着色器。✅

Redshift 支持

• inspect_redshift_materials：只读的 Redshift 检查工具，支持回退方案，可检查材质指派、预览颜色、可读参数、采用 renderEngine 风格的节点材质探测，以及通过 redshift.GetRSMaterialNodeMaster(...) 回退到 Redshift GraphView。✅ 已知问题：即使某些版本中的每材质 GraphView 回退方案成功，顶层 capabilities.redshift_module_available 标志仍可能为 false。请以各材质的 graph.backend 和 graph.graphview.redshift_module_imported 为准。
• validate_redshift_materials：检查 Redshift 材质设置和连接。✅ ⚠️（Redshift 材质尚未完全实现）

MoGraph 与 Fields

• create_mograph_cloner：添加 MoGraph Cloner（线性、径向、网格等）。✅
• add_effector：添加 MoGraph Effector（随机、平滑等）。✅
• apply_mograph_fields：添加 MoGraph Field 并将其链接到对象。✅

动力学与物理

• create_soft_body：为对象添加软体标签。✅
• apply_dynamics：应用刚体或软体物理效果。✅

渲染与预览

• render_frame：渲染一帧并将其保存到磁盘（仅支持文件输出）。⚠️（可用，但高分辨率下会因 MemoryError: Bitmap Init failed 而失败。这是资源限制所致。）
• render_preview：渲染快速预览并返回 base64 图像（供 AI 使用）。✅
• snapshot_scene：捕获场景快照（对象 + 预览图像）。✅

兼容性计划与路线图

兼容性目标

• 短期：确保兼容 C4D 2023.1+（Python 3.9 和 3.10）
• 中期：为缺失的 MoGraph 和 Field API 添加条件处理
• 长期：如果出现需求，考虑为 R23–S26 提供可选的旧版插件模块

最近修复

• 上下文感知：通过 GUID 实现稳健的对象跟踪。创建对象的命令会返回上下文（guid、actual_name 等）。后续命令可以正确使用测试框架/服务传入的 GUID，可靠地查找对象。
• 对象查找：重构 find_object_by_name，使其能够正确处理 GUID（数字字符串格式）；修复递归错误，并提升 doc.SearchObject 失败时的可靠性。
• GUID 检测：命令处理程序（apply_material、create_mograph_cloner、add_effector、apply_mograph_fields、set_keyframe、group_objects）现在可以正确检测各种参数（object_name、target、target_name、列表项）中传入的标识符是否为 GUID，并据此进行查找。
• create_mograph_cloner：通过使用 getattr 回退方案，修复了缺少 MoGraph 参数（如 MG_LINEAR_PERSTEP）时发生的 AttributeError。还修复了查找到的对象未正确传递以供克隆的逻辑错误。
• 渲染：修复了与 doc.ExecutePasses 相关的 render_frame 中的 TypeError。snapshot_scene 现在可以正确使用正常工作的 base64 渲染逻辑。大型 render_frame 仍受内存限制。
• 注册：修复了 c4d.NilGuid 的 AttributeError。