cinema4d-mcp

Name: cinema4d-mcp
Author: ttiimmaacc

作者：ttiimmaacc29 星标更新：2025-04-30

安装使用来源：spider==github.com

项目介绍

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

Cinema4D MCP 服务器连接 Cinema 4D 和 Claude，使提示辅助的 3D 操作成为可能。

组件

C4D 插件：一个监听来自 MCP 服务器命令并执行这些命令的套接字服务器。
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 插件，请按照以下步骤操作：

复制插件文件：将 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\
启动套接字服务器：
- 打开 Cinema 4D。
- 转到扩展 > 套接字服务器插件
- 您应该会看到一个套接字服务器控制对话框窗口。点击“启动服务器”。

Claude Desktop 配置

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

打开配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- 或者使用 Claude Desktop 中的设置菜单（设置 > 开发者 > 编辑配置）。

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

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

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

<details> <summary>[待办事项] 对于已发布的服务器</summary>

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

</details>

使用

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

测试

命令行测试

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

python main.py

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

使用 MCP 测试框架进行测试

该仓库包括一个简单的测试框架，用于运行预定义的命令序列：

测试命令文件 (tests/mcp_test_harness.jsonl)：包含一系列以 JSONL 格式表示的命令，可以按顺序执行。每一行代表一个带有参数的 MCP 命令。
GUI 测试运行器 (tests/mcp_test_harness_gui.py)：一个简单的 Tkinter GUI，用于运行测试命令：
```
python tests/mcp_test_harness_gui.py
```
该 GUI 允许您：
- 选择一个 JSONL 测试文件
- 按顺序运行命令
- 查看来自 Cinema 4D 的响应

此测试框架特别适用于：

快速测试新命令
在更新后验证插件功能
复现复杂的场景以进行调试
测试不同 Cinema 4D 版本之间的兼容性

故障排除与调试

检查日志文件：
```
tail -f ~/Library/Logs/Claude/mcp*.log
```
验证 Cinema 4D 在打开 Claude Desktop 后的控制台中显示连接。
直接测试包装脚本：
```
cinema4d-mcp-wrapper
```
如果找不到 mcp 模块，请全局安装它：
```
pip install mcp
```

对于高级调试，使用 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：将选定的对象分组到一个新的 Null 下。✅
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 材质设置和连接。✅ ⚠️（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：捕获场景快照（对象 + 预览图像）。✅

兼容性计划与路线图

Cinema 4D 版本	Python 版本	兼容状态	备注
R21 / S22	Python 2.7	❌ 不支持	遗留 API 和 Python 版本过旧
R23	Python 3.7	🔍 未计划	尚未进行测试
S24 / R25 / S26	Python 3.9	⚠️ 可能（待定）	需要测试和缺失 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 和场 API 的条件处理
长期：如果需求出现，考虑为 R23–S26 支持可选的遗留插件模块