mcp-c4d-2025

中文文档：完整入门说明 · 动画、F-Curve 与序列渲染

Let an LLM drive Cinema 4D. mcp-c4d-2025 is a foundation fork of mcp-cinema4d that targets Cinema 4D 2025.3.2. It connects an MCP stdio client to the Python bridge running inside Cinema 4D so the model can inspect and edit a scene through typed tools.

Based on kumo.productions' mcp-cinema4d, with its MIT license and original copyright retained. This fork adds compatibility fixes, guarded Redshift workflows, and animation controls. Install from this source checkout; the version in this repository is not a claim that an npm release has been published.

Version 0.5.0 adds four bounded F-Curve tools for existing REAL tracks: read/sample, edit values and tangents, retime/scale, and set pre/post extrapolation. Automatic tangents remain automatic and are recalculated by C4D; this is not an arbitrary curve-shape preservation guarantee. These additions have not yet been installed or live-verified. See the F-Curve workflow.

中文使用说明与开发范围

The installed 0.4.0 candidate also passed a single-document workflow test: editable geometry, rigid parent-hierarchy animation, user-data/reference access and seven 128×128 Redshift PNG frames. This is a scoped technical test, not a complete character-rigging or production-rendering claim.

Good for:

• Scene audits — "List every object on the hero layer; flag any with non-uniform scale or missing Texture tags."

• Shot setup — "Create a 1920×1080 RenderData, a camera at (0, 150, -400), and a Take that uses both."

• Material work — "Build a Redshift node material with a noise texture driving roughness at 0.4 gain."

• Procedural edits — "On every Subdivision Surface in the scene, reduce editor/render levels by 1."

• Xpresso rigs — "Build a 3-gear meshing rig where the master gear's pitch radius dynamically drives the others' size and counter-rotation via an Xpresso graph."

Architecture

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

Two pieces to install: the MCP server (this npm package, runs as an MCP stdio process) and the bridge plugin (Python, lives inside Cinema 4D). C4D must be running for the bridge to respond.

Quickstart

Prerequisites: Windows, Node.js 24+, and a local Cinema 4D 2025 preference directory. From an absolute local checkout:

Set-Location "D:\ABSOLUTE\PATH\TO\mcp_c4d"
npm ci
npm run build
npm run install:c4d -- --dry-run

Review the printed source and destination before running the explicit --install command. Do not install into a running Cinema 4D process. The complete token, install, Codex, backup, rollback, and live-test procedure is in Codex setup.

Client configuration

Codex uses this checkout as a local STDIO MCP server. Set the same C4D_MCP_TOKEN in the Cinema 4D launch environment and the MCP server environment, use absolute Windows paths for node.exe and dist\index.js, and never commit the token. See Codex setup for the supported Settings UI, CLI, and config.toml forms.

Tools

83 tools across 17 groups are registered (82 exposed by default; arbitrary Python is opt-in). Catalog presence does not mean that a tool or group is compatible with Cinema 4D 2025.3.2. See docs/TOOLS.md for the generated reference and Compatibility for verification scope.

For a guarded Redshift workflow, call rs_get_capabilities first, then create or update materials, lights, and camera, configure AOVs and RenderData, and use rs_render last. Always pass the exact document_name. rs_set_material_pbr requires replace_graph: true before replacing an existing graph; rs_clear_aovs requires both the exact document name and force: true; rs_render is synchronous, requires force: true, and a client timeout does not cancel work already running inside Cinema 4D.

Entity handles

Every CRUD tool identifies entities by a typed handle object. The resolver raises on ambiguous names — prefer path when a scene contains duplicates.

name lookups are strict: if several entities share the name, the bridge returns an error listing up to five candidate paths so you can switch to a path-based handle. create_entity always returns the freshly-resolved handle (objects include path; shaders include both name and index) so chained edits stay stable.

Installing the bridge plugin

The local installer accepts only a drive-letter absolute Cinema 4D 2025 preference path under the current user's %APPDATA%\Maxon directory. Start with a read-only plan:

npm run install:c4d -- --dry-run

If discovery is ambiguous, pass an explicit path such as C:\Users\<WINDOWS_USER>\AppData\Roaming\Maxon\Maxon Cinema 4D 2025_<INSTALL_ID>. Only --install copies files. If the destination already exists, it is moved into <PREFERENCE>\mcp_bridge_backups\cinema4d_mcp_bridge.backup-<UTC_TIMESTAMP> before the new copy is created. Backups stay outside plugins so Cinema 4D cannot load their plugin entrypoints. See Codex setup for the reviewed install and rollback sequence.

Configuration

Security

Even without exec_python, many tools mutate state: call_command, set_params, import_scene, render, remove_entity, save_document, open_document, new_document. Treat the bridge like a local shell, not a sandbox.

• exec_python is opt-in. It runs unrestricted Python on Cinema 4D's main thread (file I/O, subprocess, network). Hidden and rejected by the bridge unless C4D_MCP_ENABLE_EXEC_PYTHON=1 is set on both the MCP server process and the Cinema 4D process. Turn it back off when you no longer need it — set-and-forget is how accidents happen.

• Python-bearing plugin types are opt-in too. Python tag (Tpython), Python generator (Opython), MoGraph Python effector, Python field (Fpython), and the Xpresso Python operator all store caller-supplied source code in their container and run it on scene evaluation — i.e. they are RCE-equivalent to exec_python. The bridge refuses create_entity, set_params, apply_xpresso_graph, and take_override operations targeting these types unless C4D_MCP_ENABLE_PYTHON_OPS=1 is set on the Cinema 4D side. Listing / reading / removing existing instances is unaffected.

• Set a shared-secret token (C4D_MCP_TOKEN). Localhost is not a trust boundary — any local process running as your user can otherwise connect. See Codex setup.

• Loopback default + remote opt-in. The bridge binds to 127.0.0.1 by default. Binding C4D_MCP_HOST to a non-loopback interface refuses to start unless C4D_MCP_ALLOW_REMOTE=1 is also set — guarding against a one-character typo (0.0.0.0) exposing C4D to the LAN.

• Only connect MCP clients you trust. Review their tool-use permissions so mutating tools (especially exec_python if opted in) are not auto-approved.

• Indirect prompt injection via scene content. Scene data (object names, parameter strings, imported file paths) flows back to the LLM through list_entities / describe / get_container / dump_shader / get_mesh. When exec_python is enabled, a malicious string in a scene can steer the model into running arbitrary Python. Don't run import_scene against untrusted .c4d / .fbx / .abc files while exec_python is on, and rely on your MCP client's per-call approval for exec_python / call_command / save_document / import_scene rather than blanket-approving them.

• Audit log. Every exec_python call records the code body to the local bridge log (%TEMP%/cinema4d_mcp_bridge.log on Windows, $TMPDIR/cinema4d_mcp_bridge.log on macOS) for after-the-fact review. The log is append-only with no rotation — prune it manually if it grows.

Troubleshooting

For plugin repair or version skew, save your work and close Cinema 4D first. From this local checkout, review the exact target before reinstalling:

npm run install:c4d -- --dry-run --preference "C:\Users\<WINDOWS_USER>\AppData\Roaming\Maxon\Maxon Cinema 4D 2025_<INSTALL_ID>"
npm run install:c4d -- --install --preference "C:\Users\<WINDOWS_USER>\AppData\Roaming\Maxon\Maxon Cinema 4D 2025_<INSTALL_ID>"

Run the second command only after the dry-run source and destination are correct. The installer preserves the previous bridge as a sibling backup; see backup and rollback.

Still stuck? Open an issue with a redacted bridge log, your OS, Cinema 4D version, and the tool call that failed. Remove tokens, private asset names, and personal paths before posting.

Known limitations

• Inherited observations are not 2025 verification. Notes about modeling_command make_editable, node assets, node material names, and other SDK behavior came from the upstream implementation and remain unverified on Cinema 4D 2025.3.2.

• list_graph_node_assets can return an empty list on builds where the Maxon asset repository doesn't expose node-template assets through the usual query path. The tool still returns supported: true with shape-correct output; treat an empty assets array as "discovery unavailable on this C4D build" and pass $type asset ids you already know (e.g. from list_graph_nodes on an existing material).

• Node material friendly names vary. apply_graph_description accepts the declarative $type strings documented by Maxon (e.g. "Standard Material"), but the resolver varies between 2024 / 2025 / 2026 builds — when in doubt, pass the fully-qualified asset id returned by list_graph_node_assets / list_graph_nodes instead.

• exec_python is the only way to seed classical-shader fixtures. A handful of E2E tests (for dump_shader) need to build a shader tree before asserting on it, so they skip cleanly when C4D_MCP_ENABLE_EXEC_PYTHON isn't set on both sides. The tools themselves don't require exec_python.

• No broad support claim is made. The foundation path is live-verified, while the Redshift tools remain offline-tested until the separate strict test:live:redshift:2025 gate passes on the installed candidate. Each gate verifies only its documented path on the exact runtime tested. See Compatibility.

Contributing

See CONTRIBUTING.md for setup, the development loop, how to add a new tool, coding style, and the PR flow.

License

MIT © 2026 kumo.productions, Inc.

Trademarks

Cinema 4D® and Maxon® are trademarks of Maxon Computer GmbH. This project is an independent, unofficial tool, not affiliated with or endorsed by Maxon.