MCP Claude AI

MCP克劳德AI服务器

MCP Claude AI服务器通过模型上下文协议将Cinema 4D连接到Claude，从而能够从AI助手进行提示辅助的3D场景操作。

目录

• 组件
• 先决条件
• 安装
• 设置
• 用法
• 测试
• 故障排除和调试
• 项目文件结构
• 工具命令
• 兼容性和路线图
• 最近修复

组件

1. C4D插件：在Cinema 4D内部运行的套接字服务器，监听来自MCP服务器的命令，并在Cinema 4D环境中执行这些命令。交付日期： mcp_server_plugin.pyp.

1. MCP服务器：一个Python服务器（FastMCP），它实现了MCP协议，并公开了通过TCP向Cinema 4D插件发送JSON命令的工具。连接可通过以下方式配置 C4D_HOST 和 C4D_PORT （默认值：127.0.0.1:5555）。

先决条件

• 4D影院（推荐R2024+）
• Python 3.9或更高版本（适用于MCP服务器）

安装

克隆仓库

克隆存储库并输入项目目录：

git clone 
cd cinema4d-mcp

安装MCP服务器包

从项目根：

pip install -e .

或者使用紫外线：

uv sync

使包装脚本可执行（类Unix系统）

chmod +x bin/cinema4d-mcp-wrapper

设置

Cinema 4D插件设置

1. 复制插件：复制 c4d_plugin/mcp_server_plugin.pyp 进入Cinema 4D的插件文件夹：

- macOS： ~/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/ - 窗户： %APPDATA%\Maxon\Maxon Cinema 4D\plugins\

1. 在C4D中启动套接字服务器:

- 开放影院4D。 - 转到扩展>套接字服务器插件。 - 在“套接字服务器控制”对话框中，单击“启动服务器”。

Claude桌面（或光标）配置

编辑MCP客户端配置，使其运行Cinema 4D MCP服务器。

开发（从项目开始）：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• 或者在Claude Desktop中：设置>开发人员>编辑配置。

添加MCP服务器条目，例如：

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

替换 /path/to/cinema4d-mcp 与这个项目的实际路径。

已安装的软件包（已发布/包装）：

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

更改配置后重新启动Claude Desktop（或MCP主机）。

用法

1. 在C4D中启动Cinema 4D套接字服务器（请参阅设置）。
2. 启动配置了cinema4d服务器的MCP客户端（例如Claude Desktop或Cursor）。
3. 使用下面列出的工具命令通过助手与Cinema 4D进行交互。

测试

命令行

直接运行服务器以确认其启动并连接到Cinema 4D：

python main.py

或者从已安装的软件包中：

cinema4d-mcp-wrapper

预期：启动日志和一条指示连接到Cinema 4D套接字的消息（如果C4D未运行或插件未启动，则显示明显故障）。

MCP测试线束

该仓库包括一个用于预定义命令序列的小型测试工具。

• 测试命令文件: tests/mcp_test_harness.jsonl --JSONL文件，其中每一行都是一个带参数的MCP命令。
• GUI测试运行器: tests/mcp_test_harness_gui.py --Tkinter GUI加载JSONL文件并按顺序运行命令。

运行GUI：

python tests/mcp_test_harness_gui.py

您可以选择一个JSONL文件，运行序列，并检查Cinema 4D的响应。可用于测试新命令、在更改后验证插件以及再现场景进行调试。

故障排除和调试

1. 日志：检查MCP客户端日志（例如Claude Desktop： ~/Library/Logs/Claude/mcp*.log 在macOS上或Windows上的等效设备上）。使用 tail -f 在相关日志上查看输出，同时再现问题。

1. 电影院4D：打开MCP客户端后，验证Cinema 4D的控制台或Socket Server UI是否显示传入连接。

1. 包装器：手动运行服务器以查看错误：

   cinema4d-mcp-wrapper

1. 缺少mcp模块：如果客户报告 mcp 找不到模块，请将其（和项目）安装在配置使用的同一Python中：

   pip install mcp
   pip install -e .

1. 高级调试：使用MCP检查器（来自modelcontextprotocol组织）运行和检查服务器，例如：

   npx @modelcontextprotocol/inspector uv --directory /path/to/cinema4d-mcp run cinema4d-mcp

替换 /path/to/cinema4d-mcp 与您的项目路径。

项目文件结构

cinema4d-mcp/
├── .gitignore
├── .python-version
├── LICENSE
├── README.md
├── main.py
├── pyproject.toml
├── setup.py
├── uv.lock
├── bin/
│   └── cinema4d-mcp-wrapper
├── c4d_plugin/
│   └── mcp_server_plugin.pyp
├── src/
│   └── cinema4d_mcp/
│       ├── __init__.py
│       ├── config.py
│       ├── server.py
│       └── utils.py
└── tests/
    ├── test_server.py
    ├── mcp_test_harness.jsonl
    └── mcp_test_harness_gui.py

• main.py：脚本入口点；添加路径和调用包 main().
• src/cinema4d_mcp/server.py：FastMCP应用程序、工具定义以及与C4D插件的TCP通信。
• src/cinema4d_mcp/config.py: C4D_HOST 和 C4D_PORT 从环境。
• bin/cinema4d-mcp-wrapper：用于查找Python的Shell脚本 mcp 并奔跑 cinema4d_mcp 作为一个模块。

工具命令

一般场景和执行

• get_scene_info：当前Cinema 4D场景摘要。
• list_objects：列出具有层次结构的场景对象。
• group_objects：将所选对象分组到新空值下。
• execute_python：在Cinema 4D中运行自定义Python代码。
• save_scene：将当前项目保存到磁盘。
• 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：生成并应用程式化或程序化着色器。

红移

• 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：快速预览渲染；为AI返回base64图像。
• 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（数字字符串格式），修复递归问题，并在以下情况下正确运行 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：缺失MoGraph参数（如MG_LINEAR_PERSTEP）的AttributeError，通过getattr回退解决；固定逻辑，因此使用正确的对象进行克隆。
• 渲染：类型错误 render_frame 大约 doc.ExecutePasses 固定的。 snapshot_scene 使用正确的base64渲染路径。大的 render_frame 仍然受到内存限制。
• 注册：的属性错误 c4d.NilGuid 固定的。