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

Cinema4D MCP 服务器将 Cinema 4D 连接到 Claude，从而实现提示辅助的 3D 操作。

目录

• 组件
• 先决条件
• 安装
• 设置
• 使用
• 开发
• 故障排除和调试
• 文件结构
• 工具命令

组件

1. C4D 插件: 一个 socket 服务器，监听来自 MCP 服务器的命令并在 Cinema 4D 环境中执行它们。
2. MCP 服务器: 一个 Python 服务器，实现了 MCP 协议并为 Cinema 4D 集成提供工具。

先决条件

• Cinema 4D
• Python 3.10 或更高版本

开发安装

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

克隆仓库

git clone https://github.com/ttiimmaacc/cinema4d-mcp.git
cd cinema4d-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. 启动 Socket 服务器:

   • 打开 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 在更新配置文件后。 <details>

<summary>[TODO] 对于已发布的服务器</summary>

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

</details>

使用

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

测试

命令行测试

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

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. 验证 Cinema 4D 在您打开 Claude Desktop 后在其控制台中显示连接。

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

• validate_redshift_materials: 检查 Redshift 材质设置和连接。

MoGraph 和 Fields

• create_mograph_cloner: 添加一个 MoGraph Cloner（线性、放射状、网格等）。
• add_effector: 添加一个 MoGraph Effector（随机、平面等）。
• apply_mograph_fields: 将 MoGraph Field 添加并链接到对象。

动力学和物理

• create_soft_body: 向对象添加一个 Soft Body 标签。
• apply_dynamics: 应用刚体或柔体物理。

渲染和预览

• render_frame: 渲染一帧并将其保存到磁盘（仅限基于文件的输出）。
• render_preview: 渲染一个快速预览并返回 base64 图像（用于 AI）。
• snapshot_scene: 捕获场景的快照（对象 + 预览图像）。

兼容性计划和路线图

Cinema 4D 版本	Python 版本	兼容性状态	备注
R21 / S22	Python 2.7	❌ 不支持	遗留 API 和 Python 版本太旧
R23	Python 3.7	🔍 未计划	目前未测试
S24 / R25 / S26	Python 3.9	⚠️ 可能 (TBD)	需要测试和缺失 API 的回退
2023.0 / 2023.1	Python 3.9	🧪 进行中	针对核心功能的回退支持
2023.2	Python 3.10	🧪 进行中	与计划的测试基础对齐
2024.0	Python 3.11	✅ 支持	已验证
2025.0+	Python 3.11	✅ 完全支持	主要开发目标

兼容性目标

• 短期: 确保与 C4D 2023.1+ (Python 3.9 和 3.10) 的兼容性
• 中期: 为缺失的 MoGraph 和 Field API 添加条件处理
• 长期: 如果有需求，考虑为 R23–S26 支持提供可选的遗留插件模块

最近的修复

• 修复了 MoGraph 字段的“应用于：无”问题
  • 通过直接插入到目标对象下修复了字段层次结构
  • 为 Cinema 4D 2025.1 实现了正确的 Field Driver 标签连接
  • 添加了多种字段链接方法以实现最大兼容性
  • 使用多个参数 ID 启用了“使用字段”复选框
  • 修复了字段可见性和父子关系问题
• 通过提供正确的参数 ID 修复了 Grid Cloner 创建问题
• 通过定义正确的字段类型常量修复了 MoGraph Fields 应用
• 改进了 list_objects 命令中的分层显示
• 提高了克隆器的可见性和创建可靠性