MCP Cinema4d

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 …

Run arbitrary Python code on Cinema 4D's main thread. SECURITY: this tool can touch any file the C4D process can reach — only expose it to trusted clients. Disabled by default; enable with C4D_MCP_ENABLE_EXEC_PYTHON=1 on both sides. Set `result = <value>` in your code to return data; stdout and stderr are captured.

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, canonical handles for the active camera / take / render data, and `marker_count` (how many timeline markers exist — list them with list_markers). 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.

Start another Cinema 4D process next to the running one, with its own bridge on the next free port, and return its id. Cinema 4D normally refuses a second instance of the same installation; this passes g_allowParallelInstance=true. Use it for isolated scratch work — testing a heavy operation or a render without touching the primary scene. Costs a full C4D start (1–2 minutes and several GB of RAM per instance); the executable is C4D_MCP_EXE or the newest installed version. Waits until the new bridge answers unless `wait` is false.

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.

List the Cinema 4D instances this server can reach and which one is active. Instance 0 is the primary (the bridge at C4D_MCP_PORT); the others were started by `launch_instance` or discovered on the neighbouring ports. Every scene tool accepts an optional `instance` argument to target one explicitly; calls without it go to the active instance (see `set_active_instance`). Status is `ready` (bridge answers), `starting` (launched, bridge not up yet — a cold start takes 1–2 minutes) or `unreachable`.

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).

Enumerate every timeline marker in the active document with its frame, time_seconds, name, colour and length_frames (c4d.documents.GetFirstMarker + GetNext). Each entry carries an `index` handle accepted by set_marker / remove_marker. Use this to verify marker placement — get_document_state only reports marker_count.

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 one timeline marker, or all of them. Pass `all:true` to clear every marker, or identify a single target by exactly one of `index` (from list_markers), `frame`, or `name` (the latter two error if several markers match). Returns `{removed: N}`.

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`. The request times out after 180 seconds; heavier renders that exceed that keep running in C4D but the call returns a timeout.

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).

Switch focus to an already-open document, identified by its list `index` (from `list_documents`) or `name`. Pass exactly one of the two. `name` errors if it matches zero or several open documents — use `index` to disambiguate. This only switches between documents already open; use `open_document` to load a file from disk.

Choose which Cinema 4D instance receives tool calls that omit the `instance` argument. This is session-wide state: when issuing calls in parallel against different instances, pass `instance` explicitly on each call instead of relying on it.

Update document-level settings: fps, frame range, current frame, active camera, active take. FPS and frame range are also mirrored onto the active render data.

Update a single port on a node addressable by its stable $id within a node material graph. Thin convenience over apply_graph_description: internally builds a {$query:{$id:node_id}, port: value} payload. Lists of 3 numbers are coerced to maxon.Vector for vector-typed ports.

Create or update a single keyframe on a resolved entity's parameter. Supports scalar (real/long/bool) and vector (x/y/z component) parameters; the bridge infers the dtype from the entity's description, or you can override it explicitly. Creates the CTrack automatically on first use.

Toggle a layer's visibility / render / lock flags in one call. Only fields explicitly passed are modified; omitted flags keep their current value. `flags` returned in the response reflects the post-update state.

Rename, recolour, move, or resize an existing timeline marker. Identify the target by exactly one of `index` (from list_markers — always unambiguous), `frame`, or `name` (the latter two error if several markers match). Pass at least one update field. Returns the updated marker's info.

Overwrite the points (and optionally polygons) of an editable object. Triangles may be passed as [a,b,c]; the bridge expands them to C4D's quad storage (a,b,c,c). If polygons is omitted, only points are rewritten and the count must match the existing topology. Wrapped in a single undo entry.

Replace the point / polygon / edge BaseSelect on an editable mesh. Existing selection of the specified kind is cleared first. Pair with `get_mesh` using `include:['selections']` to read the same channels back.

Atomically write parameter values (wrapped in one undo). Each entry is `{path, value}` where `path` is either an int id or a DescID path (e.g. [903, 'x'] = position.x). Lists of 3 numbers auto-coerce into c4d.Vector for vector-typed destinations. Returns `{applied: [{path, value}], errors: [{path, error}]}`.

Replace or extend the active document's selection. Pass `objects` (first becomes the active object), `tag`, or `material`. With `mode:'add'` the listed objects are added to the existing selection; with `mode:'replace'` (default) the prior selection is cleared first. `clear:true` deselects everything and ignores other fields.

Write an object's transform in local or global space. Pass any combination of `pos`/`rot` (HPB radians)/`scale` to patch individual components — unspecified parts keep their current value. Or pass a full 4x3 `matrix` (rows: offset, v1, v2, v3) to replace the whole transform; matrix is mutually exclusive with the decomposed fields. Space defaults to 'local' (SetMl). Use 'global' (SetMg) to write world coordinates through a parent.

Low-level Xpresso port primitive — covers cases `apply_xpresso_graph` can't express. `action:'add'` adds a new input/output port via GvNode.AddPort(port_id). `connect` wires this node's `port` to `target` (on a peer node identified by `target.node_handle`); output-vs-input direction is auto-detected. `disconnect` removes incoming connections from `port`. `set_value` writes the port's default. `remove` deletes the port. Use `list_xpresso_nodes` first to discover node path ids and existing ports.

Quit a secondary Cinema 4D instance. Unsaved documents in it are discarded without prompting. Refuses instance 0 (the primary). Instances started by `launch_instance` quit through their bridge and are terminated if that fails; other instances only accept quit when their bridge was launched with C4D_MCP_ENABLE_MULTIINSTANCE=1.

Write per-Take parameter overrides onto a target node (object / tag / material / render_data / video_post / shader). Wraps `take.OverrideNode + UpdateSceneNode + override[descid] = value`. Use this for shot-by-shot variations that share a single scene (e.g. override Focal Length per Take while one Camera is reused). Paths use the same syntax as `set_params`. If the scene's Take Manager has its "Lock Overrides" toggle off (which makes C4D refuse all override creation), the bridge enables it for the write and restores the artist's state afterward — reported as `lock_overrides_toggled` in the res…

Pop up to `steps` entries off the active document's undo stack via doc.DoUndo. Stops early if the stack empties. Returns `steps_performed` so callers can tell when fewer steps were available than requested. Default: 1 step.