内容
# MCP4D -- Cinema 4D 桥接插件
一款原生 C++ Cinema 4D 插件，通过 [模型上下文协议](https://modelcontextprotocol.io/) 将 [Claude Code](https://claude.ai/claude-code) 连接到 Cinema 4D。从终端读取场景、构建几何体、执行 Python、投射光线、捕获视口。
```
Claude Code 命令行界面
└── Python MCP 服务器（stdio，薄适配器）
└── TCP 本地主机:5555
└── C4D C++ 插件 (.xdl64)
```
## 功能
<img width="600" height="337" alt="ezgif com-video-to-gif-converter" src="https://github.com/user-attachments/assets/d5be754f-7a36-4209-8063-122892031e1c" />
Claude Code 通过 15 个原生命令获得对 Cinema 4D 的完全访问权限：
| 类别 | 命令 |
|----------|----------|
| **场景** | `ping`、`get_scene_info`、`get_object_info`、`list_materials` |
| **Python** | `execute_python` -- 在 C4D 的 Python 虚拟机中运行任意代码 |
| **光线投射** | `raycast` -- 屏幕到世界的碰撞检测 |
| **表面矩形** | `define_surface_rect`、`get_surface_rect`、`clear_surface_rect` |
| **原生操作** | `boolean`、`current_state_to_object`、`select_polys_at_rect` |
| **导入** | `import_mesh` -- OBJ、FBX、GLB、STL、USD |
| **视口** | `capture_viewport` -- 带相机数据的 PNG 快照 |
`execute_python` 中继是逃生舱。任何没有专用原生命令的操作都可以通过 C4D 的 Python API 完成。原生命令在 Python 不可靠（布尔值、CSTO）或 C++ 更佳（场景遍历、光线投射、视口捕获）时存在。
## 表面矩形工具
<img width="600" height="337" alt="ezgif com-video-to-gif-converter (1)" src="https://github.com/user-attachments/assets/f3669116-fde2-4619-8943-36bdd70233ff" />
<img width="600" height="337" alt="ezgif com-video-to-gif-converter (2)" src="https://github.com/user-attachments/assets/ce4e9ea5-cf27-41c7-9659-227989da57d9" />
一个交互式视口工具（**扩展 > 表面矩形**），允许您在任何多边形表面上单击并拖动以定义矩形。矩形数据与 MCP 共享 -- 在视口中交互式绘制，然后从 Claude Code 以编程方式读取。
用于放置导入的网格，选择多边形区域，并在表面上定义感兴趣的区域。
## 配方和技能
<img width="600" height="337" alt="MACP4D_1-ezgif com-video-to-gif-converter" src="https://github.com/user-attachments/assets/f443da9e-3ee8-44a1-a0a8-76f1e5426629" />
该插件在 `SKILLS.md` 中附带了一个配方系统，为 Claude Code 提供了常见场景类型的即用工作流程。当您描述您想要的内容（例如“黑暗的情绪化产品拍摄”或“爆炸的技术视图”）时，Claude 会将您的描述与配方匹配并逐步遵循。
当前配方包括：
- **clean-product-hero** -- 白色工作室，戏剧性照明，美化拍摄设置
- **dark-moody-tech** -- 黑色背景，带有电子产品和科技产品的彩色强调照明
- **exploded-technical** -- 工程风格的爆炸视图，干净的白色背景
- **tech-collage-cluster** -- 密集的垂直科技板块集群，编辑风格，程序纹理
您也可以通过名称引用配方（“构建技术集群”），Claude 将准确遵循。
### 教你如何工作
您也可以通过一步一步地引导 Claude Code 完成您的工作流程来教它新的配方。它从您的操作中学习并将它们保存为可重用的配方，这样您就不必重复自己。更好的是；请 Claude Code 生成带有动态字段的 Python 扩展，这样来回的过程变成了一次点击。
除了配方，`SKILLS.md` 还包括实用技能，如多边形计数，纹理大小审计和批处理删除工具，Claude 在相关时自动使用。
<img width="600" height="337" alt="ezgif com-video-to-gif-converter (4)" src="https://github.com/user-attachments/assets/2d10ec37-fe79-4bba-94f0-9231fc46d9ef" />
<img width="600" height="337" alt="ezgif com-video-to-gif-converter (5)" src="https://github.com/user-attachments/assets/c457343e-cbd0-40b9-a9d7-7ff34462ff2e" />
<img width="600" height="337" alt="ezgif com-video-to-gif-converter (3)" src="https://github.com/user-attachments/assets/248febcf-057e-422f-9f9e-36af817ee7a7" />
## 参考文档
存储库中包含编译后的参考文档，Claude 在使用特定渲染器或 API 之前会读取这些文档。这些文档包含已验证的 ID、参数值和代码模式，以便 Claude 不必在运行时猜测或查找：
| 文件 | 内容 |
|------|----------|
| `C4D_PYTHON_REFERENCE.md` | 常见的 C4D Python 方法、常量、建模命令 |
| `OCTANE_REFERENCE.md` | Octane 材质 ID、纹理节点连接、光参数、渲染设置 |
| `REDSHIFT_REFERENCE.md` | Redshift 节点材质设置、着色器图构造 |
| `INSYDIUM_REFERENCE.md` | X-Particles 和相关 Insydium 插件参考 |
这些文件是代理工作知识的一部分。您不需要自己阅读它们，但如果您发现新的 ID 或模式，可以更新它们。
## 要求
- Cinema 4D 2024 或更新版本
- Python 3.10 或更新版本（通常已与 C4D 一起安装）
- Windows（macOS 和 Linux 版本已在项目中定义但未测试）
- [Claude Code](https://claude.ai/claude-code) 命令行界面已安装
## 安装
### 快速安装
克隆存储库，然后从其文件夹运行安装脚本：
```bash
git clone https://github.com/cuneytozseker/mcp4d.git
cd mcp4d
python install.py
```
它将自动找到您的 Cinema 4D 安装、复制插件、安装 Python 依赖项，并使用 Claude Code 注册 MCP 服务器。如果您安装了多个 C4D 版本，它将询问要使用哪一个。
如果自动检测无法找到您的 C4D，请手动指定：
```bash
python install.py --c4d "C:/Program Files/Maxon Cinema 4D 2025"
```
### 手动安装
如果您更喜欢手动安装，请按照以下步骤：
#### 步骤 1：安装 C4D 插件
编译后的插件包含在存储库的 `dist/` 文件夹中：
```
dist/c4d-mcp-bridge.xdl64
```
将 `c4d-mcp-bridge.xdl64` 复制到您的 Cinema 4D 用户插件目录中。默认位置是：
```
C:\Users\<YourName>\AppData\Roaming\Maxon\Maxon Cinema 4D 2025_XXXXXXXX\plugins\c4d-mcp-bridge\
```
要找到确切的路径，请打开 Cinema 4D 并转到 **编辑 > 首选项 > 打开首选项文件夹**。`plugins` 文件夹位于其中。
如果 `c4d-mcp-bridge` 子文件夹不存在，请创建它并将 `.xdl64` 文件放入其中。
重启 Cinema 4D。您应该在 **扩展** 菜单中看到“MCP4D”，如果插件已正确加载。
#### 步骤 2：安装 Python MCP 服务器
MCP 服务器是一个小的 Python 脚本，它位于 Claude Code 和 C4D 插件之间。它需要安装一个依赖项。
打开终端（命令提示符、PowerShell 或您首选的终端）并运行：
```bash
pip install fastmcp
```
如果您有多个 Python 安装，请确保您正在使用 Python 3.10+。您可以使用 `python --version` 检查。
#### 步骤 3：使用 Claude Code 注册 MCP 服务器
告诉 Claude Code 在哪里找到 MCP 服务器脚本。在您的终端中运行：
```bash
claude mcp add cinema4d -- python "C:/path/to/c4d-mcp-bridge/mcp/server.py"
```
用您机器上存储库的实际路径替换 `C:/path/to/c4d-mcp-bridge/`。在 Windows 上使用正斜杠。
#### 步骤 4：验证连接
1. 确保 Cinema 4D 正在运行并且插件已加载
2. 在终端中打开 Claude Code
3. 要求 Claude ping Cinema 4D：
```
> ping cinema 4d
```
如果一切都已连接，您将获得 `{pong: true}` 响应。
#### 可选：自动允许 MCP 工具
默认情况下，Claude Code 将在每次使用 Cinema 4D 工具时要求您的许可。如果您希望它在没有中断的情况下工作，请在项目文件夹中创建一个名为 `.claude/settings.json` 的文件：
```json
{
"permissions": {
"allow": [
"mcp__cinema4d__*"
]
}
}
```
这告诉 Claude Code 允许所有 Cinema 4D MCP 工具而无需提示。
## 协议
TCP 协议很简单：换行分隔的 JSON，每个连接一个命令。
```
-> {"cmd": "ping"}
<- {"status": "ok", "data": {"pong": true}}
-> {"cmd": "execute_python", "args": {"code": "print(c4d.GetC4DVersion())"}}
<- {"status": "ok", "data": {"stdout": "2025200\n", "stderr": ""}}
-> {"cmd": "boolean", "args": {"object_a": "Cube", "object_b": "Sphere", "operation": "subtract"}}
<- {"status": "ok", "data": {"name": "Cube", "points": 192, "polygons": 194}}
```
## 项目结构
```
c4d-mcp-bridge/
├── source/ # C++ 插件源代码
│ ├── main.cpp # 插件入口，MessageData 注册
│ ├── socket_server.cpp/.h # Winsock2 TCP 服务器，select() 循环
│ ├── command_handler.cpp/.h # JSON 命令调度
│ ├── scene_reader.cpp/.h # get_scene_info, get_object_info, list_materials
│ ├── python_relay.cpp/.h # 通过 CPYTHON3VM 执行 python
│ ├── raycaster.cpp/.h # GeRayCollider 屏幕到世界的光线投射
│ ├── viewport_capture.cpp/.h # GetViewportImage 到 PNG
│ ├── surface_rect_tool.cpp/.h # ToolData + 视口叠加层 + UI
│ ├── native_ops.cpp/.h # 布尔值，CSTO，选择多边形
│ ├── mesh_import.cpp/.h # 合并文档 + 对齐到表面矩形
│ ├── mcp4d_dialog.cpp/.h # 插件对话框 UI
│ └── json.hpp # nlohmann/json（已包含）
├── project/
│ └── projectdefinition.txt # C4D SDK 构建配置
├── dist/
│ └── c4d-mcp-bridge.xdl64 # 预编译的插件二进制文件（Windows）
├── mcp/
│ ├── server.py # FastMCP stdio 服务器（薄 TCP 适配器）
│ └── requirements.txt # Python 依赖项
├── install.py # 自动安装脚本
├── CLAUDE.md # 代理说明和内部参考
├── SKILLS.md # 场景构建配方和实用技能
├── C4D_PYTHON_REFERENCE.md # C4D Python API 快速参考
├── OCTANE_REFERENCE.md # Octane Render ID 和模式
├── REDSHIFT_REFERENCE.md # Redshift 节点材质参考
├── INSYDIUM_REFERENCE.md # Insydium / X-Particles 参考
└── README.md # 此文件
```
## 工作原理
1. **C++ 插件** 注册了一个 `MessageData` 钩子，每 200 毫秒在 Cinema 4D 的主线程上轮询一个 TCP 套接字。
2. **Python MCP 服务器**（`server.py`）作为一个 stdio 进程，由 Claude Code 管理。它将 MCP 工具调用转换为 JSON 命令，并通过 TCP 将它们转发到插件。
3. **命令处理程序** 在插件内将传入的 JSON 分派到适当的模块：场景读取器、Python 中继、光线投射器等。
4. 所有 C++ 操作都在 C4D 的主线程上运行（通过 `CoreMessage` 钩子），确保与场景图的线程安全。
## 从源代码构建
如果您想修改 C++ 插件并自己编译它，您需要 Cinema 4D C++ SDK（R2024+）和 CMake。
```bash
# 从 Cinema 4D SDK 根文件夹（包含“plugins/”）
cmake --preset windows_vs2022_v143
cmake --build _build_v143 --target c4d-mcp-bridge --config Release
```
构建生成 `c4d-mcp-bridge.xdl64` 在：
```
_build_v143/bin/Release/plugins/c4d-mcp-bridge/
```
## 许可证
MIT
