Cinema4D MCP Server

Cinema4D MCP——模型上下文协议（MCP）服务器

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

目录

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

组件

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

先决条件

• 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/ - 窗户： C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\

1. 启动套接字服务器:

- 开放影院4D。 - 转到扩展>套接字服务器插件 - 您应该看到一个Socket Server控件对话框窗口。单击启动服务器。

Claude桌面配置

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

1. 打开配置文件:

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - 或者，使用Claude Desktop中的“设置”菜单（设置>开发人员>编辑配置）。

1. 添加MCP服务器配置:

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

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

1. 重新启动克劳德桌面 在更新配置文件之后。

[TODO] For published server

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

用法

1. 确保Cinema 4D套接字服务器正在运行。
2. 打开克劳德桌面，寻找锤子图标🔨 在输入框中，指示MCP工具可用。
3. 使用可用 工具命令 通过Claude与Cinema 4D互动。

代理技能

如果您使用代理技能，则此MCP的维护同伴技能将存在 vladmdgolam/代理技能.

该技能掌握了位于原始MCP工具之上的面向生产的指导，包括：

• 什么时候更喜欢 inspect_redshift_materials 使用ad-hoc Python进行Redshift检查
• 何时回归 execute_python_script 用于完全的C4D API访问
• 运行时或节点空间不可用时的当前Redshift限制
• 实用的MoGraph提取和调试工作流程

测试

命令行测试

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

python main.py

您应该看到输出，确认服务器已成功启动并连接到Cinema 4D。

使用MCP测试线束进行测试

该存储库包括一个用于运行预定义命令序列的简单测试工具：

1. 测试命令文件 (tests/mcp_test_harness.jsonl)：包含一系列JSONL格式的命令，可以按顺序执行。每一行代表一个MCP命令及其参数。

1. 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

1. 打开Claude Desktop后，验证Cinema 4D在其控制台中显示连接。

1. 直接测试包装器脚本：

   cinema4d-mcp-wrapper

1. 如果查找mcp模块时出错，请在系统范围内安装它：

   pip install mcp

1. 对于高级调试，请使用 MCP检查员:

   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：加载a .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 GraphView回退，通过 redshift.GetRSMaterialNodeMaster(...). ✅

已知怪癖：顶级 capabilities.redshift_module_available 旗帜仍然可以 false 在某些构建中，即使每种材质的GraphView回退成功。处理每种材料 graph.backend 和 graph.graphview.redshift_module_imported 作为权威信号。

• validate_redshift_materials：检查Redshift材料设置和连接。 ✅ ⚠️ （Redshift材料未完全实施）

MoGraph和字段

• create_mograph_cloner：添加MoGraph克隆器（线性、径向、网格等）。 ✅
• add_effector：添加MoGraph效应器（随机、纯等）。 ✅
• apply_mograph_fields：添加MoGraph字段并将其链接到对象。 ✅

动力学与物理学

• create_soft_body：向对象添加柔体标记。 ✅
• apply_dynamics：应用刚体或柔体物理。 ✅

渲染和预览

• render_frame：渲染帧并将其保存到磁盘（仅基于文件的输出）。 ⚠️ （工作正常，但由于内存错误，在大分辨率上失败：位图初始化失败。这是资源限制。）
• 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（数字字符串格式），修复递归错误，并提高文档时的可靠性。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。修复了发现的对象未正确传递以进行克隆的逻辑错误。
• 渲染：修复了与文档相关的render_frame中的TypeError。执行通行证。snapshotscene现在正确地使用了工作的base64渲染逻辑。大型render_frame仍然面临内存限制。
• 注册：修复了c4d的AttributeError。无GUID。