Cinema4D MCP — 模型上下文协议 (MCP) 服务器

Cinema4D MCP 服务器将 Cinema 4D 连接到 Claude，实现快速辅助的 3D 操作。

目录

• 成分

• 先决条件

• 安装

• 设置

• 用法

• 发展

• 故障排除和调试

• 文件结构

• 工具命令

成分

1. C4D 插件：一个套接字服务器，用于监听来自 MCP 服务器的命令并在 Cinema 4D 环境中执行这些命令。

2. MCP 服务器：一个实现 MCP 协议并提供 Cinema 4D 集成工具的 Python 服务器。

先决条件

• Cinema 4D（推荐 R2024+）

• Python 3.10 或更高版本（用于 MCP 服务器组件）

安装

要安装该项目，请按照以下步骤操作：

克隆存储库

安装 MCP 服务器包

使包装脚本可执行

设置

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。

   • 转到扩展>套接字服务器插件

   • 您应该会看到一个 Socket Server Control 对话框窗口。点击 Start Server。

Claude桌面配置

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

1. 打开配置文件：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows： %APPDATA%\Claude\claude_desktop_config.json

   • 或者，使用 Claude Desktop 中的设置菜单（设置 > 开发人员 > 编辑配置）。

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

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

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

用法

1. 确保 Cinema 4D Socket Server 正在运行。

2. 打开 Claude Desktop 并在输入框中查找锤子图标🔨，表示 MCP 工具可用。

3. 使用可用的工具命令通过 Claude 与 Cinema 4D 进行交互。

测试

命令行测试

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

您应该会看到确认服务器成功启动并连接到 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

项目文件结构

工具命令

总体场景与执行

• get_scene_info ：获取有关活动 Cinema 4D 场景的摘要信息。✅

• list_objects ：列出所有场景对象（带层次结构）。✅

• group_objects ：将选定的对象分组到新的 null 下。✅

• execute_python 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 支持

• validate_redshift_materials Redshift 材质设置和连接。✅⚠️（Redshift 材质尚未完全实现）

MoGraph 和场

• create_mograph_cloner ：添加 MoGraph 克隆器（线性、径向、网格等）。✅

• add_effector ：添加 MoGraph 效果器（随机、普通等）。✅

• apply_mograph_fields ：添加并链接 MoGraph 字段到对象。✅

动力学与物理学

• create_soft_body ：向对象添加 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、实际名称等）。后续命令能够正确使用测试工具/服务器传递的 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 fallbacks 时因缺少 MoGraph 参数（例如 MG_LINEAR_PERSTEP）而导致的 AttributeError 错误。修复了找到的对象无法正确传递进行克隆的逻辑错误。

• 渲染：修复了 render_frame 中与 doc.ExecutePasses 相关的 TypeError。snapshot_scene 现已正确使用有效的 base64 渲染逻辑。较大的 render_frame 仍然面临内存限制。

• 注册：修复了 c4d.NilGuid 的 AttributeError。