io.github.kumoproductions/mcp-cinema4d

Add a new User Data slot to any BaseList2D (common rigging / control-exposure pattern). Returns the slot's DescID (as a nested list) which can be piped into `get_params` / `set_params` as a path. dtype aliases: real, long, bool, vector, string, color, filename, time, link.

Build or mutate a node graph using maxon.GraphDescription's declarative dict syntax. Supports creating nodes (`$type`), assigning stable ids (`$id`), wiring connections via 'thisPort -> childPort' keys (the value is the nested upstream node), and setting port values inline. Example: {"$type":"Output","Surface -> outColor":{"$type":"Standard Material","$id":"mat","Base/Color":[1,0,0]}}. Works for material graphs (standard/redshift) and the scene-nodes (neutron) document graph via `scope:"document"`. For scene-nodes, `$type` must be a node-template asset id from `list_graph_node_assets` (node_space:"scenenodes"), e.g. "net.maxon.node.invert" — NOT the net.maxon.corenode:* ids; the scene-nodes path supports creation + connections + port values (graph queries/labels are material-only). Creates the graph on demand by default.

Declarative builder for an Xpresso (classic GvNodeMaster) graph — mirror of `apply_graph_description` but for Xpresso rather than Maxon node materials. Creates nodes (CreateNode) and wires connections (GvPort.Connect) in one call. Accepts an operator_id as an int (e.g. c4d.ID_OPERATOR_CONST=1001150) or short alias ('object'|'const'|'result'|'math'|'range_mapper'|'condition'|'compare'|'memory'|'iterate'|'bool'|'freeze'|'formula'|'realtovect'|'vecttoreal'|'matrix2vect'|'vect2matrix'|'link'|'spy'|'python'). Optionally creates the Texpresso tag when given an object handle and `create_tag_if_missing:true`. Example: build a `Object.Global Position -> Result` graph in three calls (create Cube → apply_xpresso_graph → EventAdd).

Link a material to an object by creating a Texture tag (or updating an existing one when `update_if_exists:true`). Avoids wrangling TEXTURETAG_* param ids by hand. Projection aliases: spherical, cylindrical, flat, cubic, frontal, spatial, uvw, shrinkwrap, camera.

Place a target (object / tag / material) on a named layer. Pass `layer:null` to clear the assignment. The layer must exist — call `create_layer` first if needed.

Run many generic ops in one RPC. Each op is applied in order; by default failures are recorded per op and the batch continues. The whole batch is wrapped in a single undo group. Useful for 'apply X to all matching entities' workflows (pair with list_entities + name_pattern to get handles).

Invoke a Cinema 4D command by plugin id via c4d.CallCommand(). Works for built-in commands (render, save, make editable, ...) and any registered command plugin.

Duplicate an entity. Supports object / tag / material / shader (via GetClone + parent insert), render_data (doc.InsertRenderData — copies VideoPosts too), video_post (rd.InsertVideoPost), and take (TakeData.AddTake, copying existing overrides). Objects default to dropping next to the source; pass `parent` to place the clone elsewhere. Returns a handle to the new entity.

Close an open document, identified by its list `index` (from `list_documents`) or `name`. Pass exactly one of the two. A document with unsaved changes is refused unless `force:true` — closing discards unsaved work without a prompt (unlike the GUI close). C4D always keeps at least one document, so closing the last one leaves a fresh empty document active.

Unified constructor for object / tag / material / shader / video_post. Handles parent linking, optional params, positions, and container slot assignment in one call. Returns the handle of the created entity (object handles include `path` for stable re-resolution) so you can chain set_params / set_keyframe. Note: `kind:"shader"` targets classical shader chains (Fusion, Colorizer, Xbitmap, …). For node-material edits (Standard node space / Redshift), use `apply_graph_description` instead. `kind:"video_post"` attaches a renderer effect (Octane 1029525, Redshift 1036219, Magic Bullet Looks 1054755, …) to a RenderData parent.

Create a LayerObject at the document's layer root. With `update_if_exists:true` the existing layer with the same name is updated in place (idempotent). Pass `color:[r,g,b]` (0..1) and/or `flags:{solo,view,render,manager,locked,...}` to configure it.

Create (or update-if-exists) a RenderData with resolution / renderer / fps / frame range in one call. Returns the render_data handle for subsequent create_take / set_params chaining.

Create or update a Take (AddTake + SetCamera + SetRenderData + SetChecked) in one call. New takes are checked by default so they participate in batch renders; pass `checked:false` to override. Returns the take handle — ideal for building per-shot take stacks programmatically.

Remove keys from a CTrack. Pass `frame` for a single-frame delete, or `start_frame` / `end_frame` (inclusive) for a range. Returns `{removed, track}`. Symmetric with `set_keyframe`.

Remove an entire CTrack (identified by `param_id` + optional `component`) from the target. Returns `{removed: bool}`.

Dump all description parameters (id, name, cycle enum, current value) of a C4D entity resolved by handle. Use this to discover parameter IDs before reading/writing.

Recursively dump a shader (resolved from a handle) into JSON. **Classical materials only** — node materials (Standard node space / Redshift / etc.) expose their shading as a maxon node graph; use `list_graph_nodes` / `apply_graph_description` for those instead. Captures type_id / type_name / name per node; promotes c4d.Xbitmap paths to a "file" field; heuristically surfaces image-like strings hiding in other shader BaseContainers as "file_candidates"; and expands shader links stored inside the container as "linked_shaders" (the shape used by Fusion / Colorizer whose internals don't appear via GetDown). Pair with list_entities kind=shader to discover shader handles.

Dump the raw BaseContainer of a C4D entity (including hidden keys that don't show up in `describe`, e.g. Octane AOV shader slots at 3740/3741). Filter by key range to narrow output.

One-shot reader for the active document's key fields: fps, min/max and loop frame range, current frame, document name/path, and canonical handles for the active camera / take / render data. Pairs with `set_document` for the writer side.

Report which node spaces a material exposes a graph in, which one is currently active, and the alias table the bridge understands. Use this before `apply_graph_description` to confirm the right `node_space` is addressable on this build / material.

Read the keys on a specific animation track. Combine with list_tracks to discover which (param_id, component) pairs are animated. Returns `[{frame, value, interp}]`. Optional start_frame / end_frame clip the range inclusively.

Read points and polygons (or spline segments) from an editable PointObject / PolygonObject / SplineObject. Primitives (Cube, Sphere, …) must be converted first via `modeling_command` make_editable. Triangles are returned as [a,b,c] (c==d in C4D storage), quads as [a,b,c,d]. Point and polygon counts are capped to 50,000 by default to protect JSON payload size — override via max_points / max_polys.

Return the layer currently assigned to a target entity (object / tag / material), or null if unassigned.

Read parameter values on a C4D entity by id or DescID path. Each id may be: an int (top-level), a list [a, b, …] (chained DescID; dtypes inferred from the description), or contain 'x'/'y'/'z' for vector sub-components (e.g. [903, 'x'] = position.x). For explicit dtypes use [[id, 'real|long|bool|vector'], …]. Returns `{values: [{path, value}]}` in request order. Discover ids via `describe`.

Read the active document's current selection: the active object (primary), all selected objects, and the active tag / material. Useful for reacting to the user's current focus without asking them to re-pick entities. Returns canonical handles so results can be piped directly into describe / set_params / etc.

Merge an external file (abc/fbx/obj/c4d/etc.) into the active document via MergeDocument. Returns the newly-imported top-level objects so they can be chained with set_params / create_entity / create_take. Optionally re-parents them under an existing object and renames the first root.

Enumerate the documents currently open in Cinema 4D. Each entry has its list `index` (the handle accepted by `set_active_document`), name, path and whether it is the active document. `get_document_state` only reports the active document; this is how you discover the others before switching.

Enumerate scene entities of a given kind. Returns compact summaries (name, type_id, type_name, plus kind-specific fields — `is_active` for take / material / render_data). For kind=object also supports type_ids / tag_types / max_depth filters and include_tags / include_params to read data inline — so you can find 'all cubes with a Ttexture tag and their position in one call' without falling back to exec_python. Use this first to find what exists before `describe`/`set_params`. **Note:** kind=shader walks classical shader chains; for node-material graphs use `list_graph_nodes`.

Enumerate registered node-template asset ids for a node space — the ids you pass to `apply_graph_description` as `$type`. For the scene-nodes (neutron) space, results are filtered to the templates actually addable there (e.g. 'net.maxon.node.invert', 'net.maxon.node.access.composecolor64'); note these differ from the net.maxon.corenode:* ids that `list_graph_nodes` reports for existing nodes. `supported:false` comes back when the C4D build lacks the maxon framework.

Walk a node graph and return a flat list of nodes. Target either a node-based material (via `handle`) or the active document's scene-nodes graph (via `scope:'document'`). `supported:false` comes back when the maxon framework is unavailable or no graph exists in the requested space.

Enumerate every LayerObject in the active document. Each entry returns the layer's name, optional color [r,g,b], and its flag dict (solo / view / render / manager / locked / generators / deformers / expressions / animation / xref).

Read the per-clone transforms from a MoGraph generator (Cloner / Matrix / Tracer / …). The bridge forces a scene pass so the MoData array is populated before sampling. Returns `{count, returned, clones: [{index, pos, matrix?}]}`. `supported:false` when the build lacks c4d.modules.mograph or when the handle isn't a MoGraph generator.

Generalized plugin enumerator. Pass plugin_type (e.g. "material", "shader", "video_post", "command") or a raw int to FilterPluginList. Each entry includes "plugin" (parent folder of the binary, e.g. "OctaneRender 1.7.1") and "plugin_file" (binary basename) for host-plugin attribution. Filter results by name_pattern and/or plugin_pattern regex.

Enumerate CTracks on the resolved entity. Returns `{name, param_id, component, dtype, key_count}` per track so callers can pipe the results straight into get_keyframes / set_keyframe. Vector tracks (Position, Rotation, Scale) surface as separate entries per component.

Enumerate the User Data slots on a target. Each entry carries `{desc_id, name, dtype, value}`. Feed `desc_id` back into `remove_user_data` / `get_params` / `set_params` as a DescID path.

Walk an Xpresso (Texpresso / GvNodeMaster) tag and return a flat list of its GvNodes. Each entry carries a stable dotted-index path id ('0.2' = root's first child, its third child) plus port summaries. Use the id to address nodes from `apply_xpresso_graph`, `set_xpresso_port`, `remove_xpresso_node`, or any handle-taking tool via `{kind:'gv_node', tag, id}`. Accepts either a tag handle (Texpresso) or an object handle (uses that object's first Texpresso tag).

Run a Cinema 4D modeling operation via c4d.utils.SendModelingCommand on one or more target objects. Commands that produce new geometry (Current State to Object, Connect / Join, Split, Explode Segments) return handles to the inserted results; in-place commands (Make Editable, Subdivide, Triangulate, …) return the mutated targets. Aliases: current_state_to_object / cso, make_editable, connect / join, connect_delete, subdivide, triangulate, untriangulate, reverse_normals, align_normals, optimize, center_axis, split, explode_segments, melt, collapse, dissolve.

Reparent a node under a new parent, promote it to the top of its hierarchy, or reorder it relative to a sibling. Works on objects, takes, and render_data — siblings/parents must share the moved node's kind. Exactly one destination field must be provided (`parent`, `before`, `after`, or `to_root:true`). For takes, `to_root:true` reparents under Main; the Main take itself cannot be moved. Returns the node's new canonical handle so follow-up edits remain stable.

Insert a fresh empty BaseDocument into C4D's document list and (by default) switch focus to it. Useful for starting a clean scene without overwriting the current one.

Load a Cinema 4D scene file as a new document. Unlike `import_scene` (which merges into the current doc), this opens the file as its own document. Pass `make_active:true` (default) to switch focus to the loaded document. Differs from `import_scene` which calls MergeDocument.

Check connectivity to the Cinema 4D bridge plugin.

Quick agent-friendly verification render. Uses the Viewport renderer with the active editor view temporarily switched to Constant Shading (Lines) — sketch-style and fast. Independent of the active RenderData (built freestanding, never inserted) and restores BaseDraw / camera / time / take in finally. Returns a base64 PNG inline so the agent can directly view it. Use `view: top|bottom|left|right|front|back` for an auto-framed temp camera, or `camera` to render through a named scene camera. Pass `save_path` to also write the PNG to disk.

Delete the resolved entity (wrapped in an undo step).

Delete a node by id from a node-material graph. The id must match the node's stable maxon.Id (as reported by list_graph_nodes or assigned via $id in apply_graph_description).

Delete a User Data slot by its DescID path (as returned by `list_user_data` or `add_user_data`). Wrapped in undo.

Delete a GvNode from an Xpresso graph. The handle must be a gv_node handle pointing at the target (use `list_xpresso_nodes` to discover its path id). All incoming / outgoing connections on the node are severed automatically.

Render the active Cinema 4D document at its currently-active render data settings. To change resolution / renderer / frame range / etc., adjust the active RenderData first via `create_render_data` (with `update_if_exists:true` on the active RD) or `set_params`. May take up to 60 seconds.

Clear scene state in one RPC. With `prefix` (e.g. 'e2e_') removes only objects / materials / non-active render data / non-main takes whose name starts with the prefix, then flushes the undo buffer — cheap cleanup for test suites. Without prefix, swaps the active document for a fresh empty BaseDocument (everything goes). Much faster than chained remove_entity calls when cleanup involves animated objects.

Evaluate the scene at each requested frame and return the object's transform. Useful to verify alembic / constraint / xpresso-driven animation without writing a bespoke exec_python sampler.

Save the active document to disk. Path must be absolute; the parent directory must exist. Supported formats: c4d (default), abc / alembic, fbx, obj, stl, ply, usd / usda, gltf. With `copy:true` the document's internal name/path is left unchanged (Save-As-Copy behaviour).