mcp-cinema4d

mcp-cinema4d

让大模型驱动 Cinema 4D。mcp-cinema4d 将兼容 MCP 的客户端（Claude Desktop、Claude Code 或任何其他支持 stdio 的 MCP 客户端）连接到正在运行的 Cinema 4D 2026 会话，使模型能够通过带类型、可安全撤销的工具层检查场景层级、编写镜头、构建节点材质并搭建动画绑定——而不是把任意 Python 代码粘贴到 Script Manager 中。

日本語 简体中文

重要

Cinema 4D 现已内置官方 MCP 服务。 从 Cinema 4D 2026.4 起，Maxon 在 Cinema 4D 自身中内置了一个 MCP 服务：无需安装，在 Preferences → MCP 中设置，并由 Maxon 提供支持。如果你使用 2026.4 或更高版本，并且只是想在 Cinema 4D 中使用 AI 助手，请从那里开始——参见 Maxon 的 MCP Server 页面和文档。

mcp-cinema4d 是一个独立的社区项目。在内置服务不适用的情况下，它仍然是一个选择：

• Cinema 4D 2026.0–2026.3，这些版本没有内置服务。
• 从一个会话管理多个 Cinema 4D 进程（多实例模式），内置服务的文档未涵盖这一点。
• 开源——你可以自行阅读、审查或扩展这些工具和桥接层。

不要在同一客户端中同时注册两个服务。 它们的工具集有重叠（例如两者都暴露 exec_python），因此模型会收到两套相互竞争的 Cinema 4D 工具。Maxon 的 FAQ 同样要求你在使用内置服务时关闭第三方服务。

适用于：

• 场景审计——"列出 hero 图层上的每个对象；标记任何具有非均匀缩放或缺失 Texture 标签的对象。"
• 镜头设置——"创建一个 1920×1080 的 RenderData、一个位于 (0, 150, -400) 的摄像机，以及一个同时使用两者的 Take。"
• 材质工作——"构建一个 Redshift 节点材质，用噪声纹理以 0.4 增益驱动粗糙度。"
• 程序化编辑——"将场景中每个 Subdivision Surface 的编辑器/渲染级别减少 1。"
• Xpresso 绑定——"构建一个 3 齿轮啮合绑定，其中主齿轮的节圆半径通过 Xpresso 图表动态驱动其他齿轮的大小和反向旋转。"

注意

除非你清楚这会产生什么后果，否则不要继续。 一个与 Cinema 4D 建立实时连接的 LLM 可以读取你的场景、写入场景，并且（如果你选择启用）在你的机器上执行任意代码。具体来说：

1. 你的场景数据会离开你的机器。 对象名称、层级路径、材质/参数值、导入的文件路径——凡是 LLM 通过 list_entities / describe / get_container / dump_shader / get_mesh 读取的内容——都会被转发给你所选择的 LLM 提供商，并可能被你的 MCP 客户端记录。处于 NDA 之下或涉及未发布的 IP？请先与你的工作室/法务团队确认，该提供商的保留策略以及你客户端的日志是可以接受的。
2. LLM 会获得写入权限。 它可以创建、修改和删除对象、标签、材质、Take、渲染数据和图层；导入 / 合并 / 打开 / 保存文件；以及渲染。Ctrl/Cmd-Z 可以覆盖大多数编辑——但 save_document、open_document、render 以及某些 call_command 调用不行。
3. 任意 Python 默认关闭。 exec_python 会以 Cinema 4D 进程的完整权限运行不受限制的代码（文件 I/O、子进程、网络）。只有在两端都设置了 C4D_MCP_ENABLE_EXEC_PYTHON=1 时才会启用；不再需要时请将其重新关闭。对于在容器中存储 Python 源代码的插件类型也是如此——Python 标签、Python 生成器、MoGraph Python 效果器、Python 场以及 Xpresso Python 运算符。创建或编辑它们被单独的 C4D_MCP_ENABLE_PYTHON_OPS=1 选择启用所限制，因为它们的代码参数在 RCE 方面等同于 exec_python。

首次使用前：备份（或提交）你的场景，先在一个一次性项目上开始，并保持你的 MCP 客户端的每次调用审批提示处于启用状态。在将桥接暴露到回环地址之外前，请参阅安全性。

---

架构

MCP client
   ↓ stdio
MCP server  (this repo, Node.js)
   ↓ TCP, JSON Lines (default 127.0.0.1:18710)
cinema4d_mcp_bridge  (Python plugin inside C4D)
   ↓
Cinema 4D

需要安装两部分：MCP 服务（本 npm 包，作为 MCP stdio 进程运行）和桥接插件（Python，运行在 Cinema 4D 内部）。桥接要响应，C4D 必须正在运行。

快速开始

假设你已经安装了 Cinema 4D 2026.0.0+ 和 Node.js 24+。

1. 将桥接插件安装到 Cinema 4D（一次性操作）。 从 Releases 页面 下载最新的 cinema4d_mcp_bridge-<version>.zip，并将 cinema4d_mcp_bridge/ 文件夹解压到你的 Cinema 4D 插件 目录中（各平台的路径见安装桥接插件）。

2. 启动（或重启）Cinema 4D。 C4D 控制台应打印 [cinema4d_mcp_bridge] listening on 127.0.0.1:18710。

3. 从命令行对 MCP 服务进行冒烟测试：

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ping","arguments":{}}}' \
     | npx -y @kumoproductions/mcp-cinema4d
   #   → {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"pong\": true, ...}"}]}}
   

然后将其接入你的 MCP 客户端（见客户端配置）并尝试：

“列出场景中的每个对象，然后在原点上方 200 单位处添加一个名为 hero 的立方体。”

LLM 会依次调用 list_entities → create_entity；你应该会看到视口中出现一个新的立方体。

更喜欢从本地检出运行？源码安装流程见 CONTRIBUTING.md。

客户端配置

生成一个随机 token，并将其同时设置到 MCP 服务进程（通过下方客户端的 env 映射）和 Cinema 4D 启动环境中。桥接会拒绝不匹配的请求（常量时间比较）；Node 客户端会自动转发该值。强烈建议这样做——在共享工作站上，localhost 并不是信任边界。

openssl rand -hex 16

在客户端中注册 MCP 服务，并将 token 放入 env 映射：

{
  "mcpServers": {
    "cinema4d": {
      "command": "npx",
      "args": ["-y", "@kumoproductions/mcp-cinema4d"],
      "env": {
        "C4D_MCP_TOKEN": "paste-your-random-hex-here"
      }
    }
  }
}

客户端	配置文件
Claude Desktop / Claude Code	%APPDATA%\Claude\claude_desktop_config.json（Windows） · ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
其他 MCP 客户端	请参阅该客户端关于注册 stdio 服务的文档

同样的 C4D_MCP_* 变量也必须设置在 Cinema 4D 启动环境中——桥接插件会在 C4D 启动时读取它们。macOS：open -a "Cinema 4D" --env C4D_MCP_TOKEN=...（或在启动前在 shell 配置文件中 export）。Windows：设置为用户环境变量并重启 C4D。

要更改桥接套接字，请在同一 env 映射中与 C4D_MCP_TOKEN 一起设置 C4D_MCP_PORT（以及可选的 C4D_MCP_HOST——参见 安全），同时还要设置 C4D 启动环境。

工具

17 个组中共有 72 个工具。大模型会根据提示词自行选择工具——你很少需要直接调用它们。有关包含每个工具说明的完整表格，请参见 docs/TOOLS.md。

分组	数量	包含内容
基础	4	ping、render、preview_render（视口渲染器 + 常量线，返回内联 PNG）、reset_scene。
脚本风格	5	exec_python（需主动启用）、call_command、list_plugins、undo、batch —— 逃生舱 + 按撤销分组的多操作。
通用 CRUD	9	list_entities、describe、get_params/set_params、get_container、dump_shader、create_entity、remove_entity、set_keyframe。
镜头设置	11	文档状态、fps / 帧范围 / 摄像机、import_scene（合并）、RenderData + Take、take_override、时间线标记（create_marker / list_markers / set_marker / remove_marker）、sample_transform。
选择 · 层级	4	活动选择的读取 / 写入；重新设置父级、重新排序、克隆。
建模 · 网格	4	modeling_command（CSO / 使可编辑 / 连接 / 细分 / …）、get_mesh、set_mesh、set_mesh_selection。
文档 I/O	6	save_document、open_document、new_document、list_documents、set_active_document（在已打开的文档之间切换）、close_document（未保存更改时强制拦截）。
节点图	10	节点材质图（遍历 / 资产枚举 / apply_graph_description / 逐端口编辑 / 移除）以及 Xpresso（GvNodeMaster）图（list_xpresso_nodes / apply_xpresso_graph / set_xpresso_port / remove_xpresso_node）。
标签助手 · 动画	5	assign_material；list_tracks、get_keyframes、delete_keyframe、delete_track。
变换 · 用户数据 · MoGraph	5	set_transform；add_user_data / list_user_data / remove_user_data；list_mograph_clones。
图层	5	枚举、创建、分配、查询、标志切换（独奏 / 视图 / 渲染 / 锁定 / …）。
实例（需主动启用）	4	list_instances、set_active_instance、launch_instance、stop_instance —— 从单个服务驱动多个 Cinema 4D 进程；除非 C4D_MCP_ENABLE_MULTIINSTANCE=1，否则隐藏。

实体句柄

每个 CRUD 工具都通过一个带类型的 handle 对象来标识实体。当名称有歧义时，解析器会抛出错误——当场景中存在重名对象时，请优先使用 path。

类型	结构
object	{kind:"object", name:"Cube"} 或 {kind:"object", path:"/Root/Character/Hip"}
render_data	{kind:"render_data", name:"VFX_Shot002"}
take	{kind:"take", name:"VFX_Shot002"}
material	{kind:"material", name:"Concrete"}
tag	{kind:"tag", object:"Cube", type_id:1029524, tag_name?:"..."}（或使用 object_path 代替 object）
video_post	{kind:"video_post", render_data:"VFX_Shot002", type_id:1029525}
shader	{kind:"shader", owner:<handle>, name?:"Layer 0"} 或 {..., index:0}
plugin_options	{kind:"plugin_options", plugin_id:"abc"|1028082, plugin_type?:"scene_saver"} — 导出器 / 导入器私有设置 BC

name 查找是严格的：如果多个实体共享同一名称，桥接层会返回一个错误，列出最多五个候选路径，以便你改用基于路径的句柄。create_entity 始终返回刚解析出的句柄（对象包含 path；着色器同时包含 name 和 index），从而保证链式编辑的稳定性。

安装桥接插件

从 Releases 获取最新的 cinema4d_mcp_bridge-<version>.zip，并将内层的 cinema4d_mcp_bridge/ 文件夹解压到你的 Cinema 4D 插件目录中：

操作系统	典型的插件目录
Windows	%APPDATA%\Maxon\Maxon Cinema 4D <VERSION>\plugins\
macOS	~/Library/Preferences/Maxon/Maxon Cinema 4D <VERSION>/plugins/

你也可以通过 Cinema 4D 的 Preferences → Plugins → Add 注册一个自定义搜索路径，并将 zip 解压到那里。

解压后启动（或重启）Cinema 4D。插件仅在 C4D 重启时才会重新加载。

请将插件版本与你运行的 npm 包版本保持一致——版本不匹配会在桥接日志中显示为 unknown command: <tool>。如果你想改用开发版检出，请参阅 CONTRIBUTING.md。

说明

官方发行版仅来自两个地方： npm 包 @kumoproductions/mcp-cinema4d 以及 GitHub Releases 页面 kumoproductions/mcp-cinema4d。如果你从其他任何地方获得了声称是本插件的 zip 或带作用域的 npm 包，请将其视为不可信。

配置

变量	侧	默认值	说明
C4D_MCP_HOST	两侧	127.0.0.1	TCP 桥接的主机。旧版别名：C4D_BRIDGE_HOST（Node）、C4D_MCP_BRIDGE_HOST（插件）。
C4D_MCP_PORT	两侧	18710	TCP 桥接的端口。旧版别名：C4D_BRIDGE_PORT、C4D_MCP_BRIDGE_PORT。
C4D_MCP_ENABLE_EXEC_PYTHON	两侧	未设置	需主动启用。 在两侧均设为 1（或 true/yes/on）以暴露 exec_python 工具。参见安全性。
C4D_MCP_ENABLE_PYTHON_OPS	C4D 插件	未设置	需主动启用。 设为 1 以允许创建 / 编辑包含 Python 的插件类型（Python 标签、Python 生成器、MoGraph Python 效果器、Python 场（Fpython，440000277）、Xpresso Python 运算符）。默认关闭 — 其代码参数等同于 exec_python 的 RCE 风险。
C4D_MCP_TOKEN	两侧	未设置	共享密钥。在 C4D 侧设置后，Node 客户端必须发送相同的值。强烈建议设置。
C4D_MCP_ALLOW_REMOTE	C4D 插件	未设置	将 C4D_MCP_HOST 绑定到非回环接口所必需的。否则桥接将拒绝启动。
C4D_MCP_ENABLE_MULTIINSTANCE	MCP 服务	未设置	需主动启用。 设为 1 以暴露实例工具（list_instances、set_active_instance、launch_instance、stop_instance），并为其他所有工具添加可选的 instance 参数。参见多个 Cinema 4D 实例。
C4D_MCP_EXE	MCP 服务	自动检测	用于 launch_instance 的 Cinema 4D 可执行文件。默认使用 C:\Program Files\Maxon Cinema 4D <ver>（Windows）或 /Applications/Maxon Cinema 4D <ver>（macOS）下最新的安装。
C4D_MCP_MAX_INSTANCES	MCP 服务	3	实例槽位，包括主实例；实例 id 监听 C4D_MCP_PORT + id。

多个 Cinema 4D 实例

默认关闭。在 MCP 服务上设置 C4D_MCP_ENABLE_MULTIINSTANCE=1，即可从一个服务驱动多个 Cinema 4D 进程——例如，在主要场景保持不变的同时，用一个临时实例进行繁重的测试渲染。

• list_instances 显示每个可访问的实例。实例 0 是主实例（C4D_MCP_PORT）；其他实例位于 C4D_MCP_PORT + id，因此 id 在服务重启后保持稳定，之前会话启动的实例也会被重新识别。
• launch_instance 会以 g_allowParallelInstance=true（Cinema 4D 自身的开关，用于解除其每次安装仅允许一个实例的限制）、自己的桥接端口以及服务的环境（包括 token 和各项启用选项）启动另一个 Cinema 4D。冷启动需要 1–2 分钟，每个实例占用数 GB 内存；C4D_MCP_MAX_INSTANCES 限制总数（默认 3，包含主实例）。
• 其他所有工具都新增了可选的 instance 参数。不带该参数的调用会发往活动实例（set_active_instance）。当并行对不同实例发起调用时，请显式传入 instance——活动实例是共享的会话状态。
• stop_instance 会退出一个次要实例，并丢弃其未保存的文档。它绝不会以实例 0 为目标，并且桥接仅在 其自身 环境中设置了 C4D_MCP_ENABLE_MULTIINSTANCE 时才响应 quit——对启动的实例为 true，对你自行启动的 Cinema 4D 则不是。
• 由服务启动的实例在服务退出后会继续运行。所有实例共享一个首选项文件夹，最后退出的实例会写入首选项——请避免在临时实例中更改设置。

安全

即使没有 exec_python，许多工具也会更改状态：call_command、set_params、import_scene、render、remove_entity、save_document、open_document、new_document。请把该桥接视为本地 shell，而不是沙箱。

• exec_python 需显式启用。 它会在 Cinema 4D 的主线程上运行不受限制的 Python（文件 I/O、子进程、网络）。除非在 MCP 服务进程和 Cinema 4D 进程两者上都设置 C4D_MCP_ENABLE_EXEC_PYTHON=1，否则该工具会被隐藏并被桥接拒绝。不再需要时请将其重新关闭 —— 设置后就不管，正是事故发生的根源。
• 含 Python 的插件类型同样需显式启用。 Python 标签（Tpython）、Python 生成器（Opython）、MoGraph Python 效果器、Python 场（Fpython）以及 Xpresso Python 操作器都会在其容器中存储调用方提供的源代码，并在场景求值时运行它 —— 也就是说，它们与 exec_python 在 RCE 意义上等效。除非在 Cinema 4D 侧设置 C4D_MCP_ENABLE_PYTHON_OPS=1，否则桥接会拒绝针对这些类型的 create_entity、set_params、apply_xpresso_graph 和 take_override 操作。列出 / 读取 / 移除现有实例不受影响。
• 设置共享密钥令牌（C4D_MCP_TOKEN）。 Localhost 并非信任边界 —— 否则任何以你的用户身份运行的本地进程都能连接。JSON 片段见 客户端配置。
• 默认回环 + 远程需显式启用。 桥接默认绑定到 127.0.0.1。将 C4D_MCP_HOST 绑定到非回环接口时，除非同时设置 C4D_MCP_ALLOW_REMOTE=1，否则会拒绝启动 —— 以防一个字符的笔误（0.0.0.0）就把 C4D 暴露到局域网。
• 多实例模式会生成进程。 在 C4D_MCP_ENABLE_MULTIINSTANCE=1 时，launch_instance 会启动 Cinema 4D 可执行文件。该二进制文件仅来自 C4D_MCP_EXE 或默认安装位置 —— 绝不来自工具参数 —— 并且新进程会继承服务的环境，因此令牌和每个 C4D_MCP_ENABLE_* 显式启用项也同样适用于它。默认关闭。
• 只连接你信任的 MCP 客户端。 检查它们的工具使用权限，确保会更改状态的工具（尤其是启用后的 exec_python）不会被自动批准。
• 经由场景内容的间接提示词注入。 场景数据（对象名称、参数字符串、导入的文件路径）会通过 list_entities / describe / get_container / dump_shader / get_mesh 回流到大模型。当启用 exec_python 时，场景中的恶意字符串可能诱导模型运行任意 Python。在 exec_python 开启时，不要对不可信的 .c4d / .fbx / .abc 文件运行 import_scene，并且应依赖你的 MCP 客户端对 exec_python / call_command / save_document / import_scene 的逐次调用批准，而不是一概批准。
• 审计日志。 每次 exec_python 调用都会将代码正文记录到本地桥接日志（Windows 上为 %TEMP%/cinema4d_mcp_bridge.log，macOS 上为 $TMPDIR/cinema4d_mcp_bridge.log），以供事后审查。该日志仅追加、不轮转 —— 若其增长过大请手动清理。

export C4D_MCP_TOKEN="$(openssl rand -hex 16)"   # set in C4D launch env too
npx -y @kumoproductions/mcp-cinema4d

疑难解答

症状	可能原因 / 解决方法
Cannot connect to Cinema 4D bridge at 127.0.0.1:18710	C4D 未运行、插件未加载，或防火墙阻止了 localhost。检查 C4D 控制台中的 listening on … 行，并查看 %TEMP%/cinema4d_mcp_bridge.log（Windows）/ $TMPDIR/cinema4d_mcp_bridge.log（macOS）。
插件已加载，但 listening 行始终未打印	通常是 cinema4d_mcp_bridge.pyp 中的 Python 导入错误。检查 C4D 控制台；常见原因是旧版本安装遗留的陈旧文件——删除目标文件夹并重新解压最新发布 zip，然后重启 C4D。
listening on 127.0.0.1:18710 失败，报错 OSError: address already in use	另一个进程已占用该端口。要么退出该进程，要么同时设置 C4D_MCP_PORT（C4D 侧）以及 MCP 服务启动命令中的相同值。
unknown command: <tool>	桥接插件比 npm 包版本旧。下载匹配的发布 zip，重新解压到你的插件文件夹，然后重启 C4D。
object name '…' is ambiguous	两个或更多场景对象共用同一名称。使用基于路径的句柄：{kind:"object", path:"/A/B/C"}。错误信息中包含候选路径。
exec_python is disabled on this C4D instance	exec_python 默认关闭。在 Cinema 4D 启动环境以及 MCP 服务 env 映射中都设置 C4D_MCP_ENABLE_EXEC_PYTHON=1，然后重启 C4D。参见 Security。
requires C4D_MCP_ENABLE_PYTHON_OPS=1 …	你尝试创建或编辑一个包含 Python 的实体（Python 标签、Python 生成器、MoGraph Python 效果器、Python 场、Xpresso Python 操作器）。默认关闭。在 Cinema 4D 启动环境中设置 C4D_MCP_ENABLE_PYTHON_OPS=1 并重启。

仍然遇到问题？请提交一个 issue，并附上桥接日志、你的操作系统、Cinema 4D 版本，以及失败的工具调用。

已知限制

• modeling_command make_editable 在 Cinema 4D 2026 上不可靠。 SDK 对 MCOMMAND_MAKEEDITABLE 的 SendModelingCommand 处理在不同构建版本之间有所变化——有时它返回新的多边形对象，有时它会移除源对象而不插入替代对象。当你需要保证得到多边形副本时，请改用 current_state_to_object（桥接层会为你插入结果并返回其句柄）。
• list_graph_node_assets 在某些构建版本上可能返回空列表，这些构建版本的 Maxon 资产仓库不通过常规查询路径暴露节点模板资产。该工具仍会返回 supported: true 且输出形状正确；请将空的 assets 数组视为“此 C4D 构建版本上无法发现资产”，并传入你已知的 $type 资产 id（例如来自现有材质上的 list_graph_nodes）。
• 节点材质的友好名称各不相同。 apply_graph_description 接受 Maxon 文档中声明的 $type 字符串（例如 "Standard Material"），但解析器在 2024 / 2025 / 2026 构建版本之间有所差异——如有疑问，请改为传入由 list_graph_node_assets / list_graph_nodes 返回的完全限定资产 id。
• exec_python 是填充经典着色器测试夹具的唯一方式。 少数 E2E 测试（针对 dump_shader）需要在对其进行断言之前构建着色器树，因此当两端都未设置 C4D_MCP_ENABLE_EXEC_PYTHON 时，它们会干净地跳过。这些工具本身并不需要 exec_python。
• 未测试较旧的 Cinema 4D 版本。 CI + E2E 测试套件以 C4D 2026 为目标。桥接层使用 getattr 回退来保护可选的 SDK 常量，因此大多数工具在 2024 / 2025 上可能也能工作——但我们不验证这一点，也不接受无法在 2026 上复现的 bug 报告。

贡献

有关设置、开发循环、如何添加新工具、编码风格以及 PR 流程，请参阅 CONTRIBUTING.md。

许可证

MIT © 2026 kumo.productions, Inc.

商标

Cinema 4D® 和 Maxon® 是 Maxon Computer GmbH 的商标。本项目是一个独立的、非官方工具，与 Maxon 无关联，也未获得其认可。