Skip to main content
Glama

Cinema4D MCP โ€” Model Context Protocol (MCP) Server

Cinema4D MCP Server connects Cinema 4D to Claude, enabling prompt-assisted 3D manipulation.

Table of Contents

Related MCP server: Cinema4D MCP Server

Components

  1. C4D Plugin: A socket server that listens for commands from the MCP server and executes them in the Cinema 4D environment.

  2. MCP Server: A Python server that implements the MCP protocol and provides tools for Cinema 4D integration.

Prerequisites

  • Cinema 4D (R2024+ recommended)

  • Python 3.10 or higher (for the MCP Server component)

Installation

To install the project, follow these steps:

Clone the Repository

git clone https://github.com/ttiimmaacc/cinema4d-mcp.git
cd cinema4d-mcp

Install the MCP Server Package

pip install -e .

Make the Wrapper Script Executable

chmod +x bin/cinema4d-mcp-wrapper

Setup

Cinema 4D Plugin Setup

To set up the Cinema 4D plugin, follow these steps:

  1. Copy the Plugin File: Copy the c4d_plugin/mcp_server_plugin.pyp file to Cinema 4D's plugin folder. The path varies depending on your operating system:

    • macOS: /Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/

    • Windows: C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\

  2. Start the Socket Server:

    • Open Cinema 4D.

    • Go to Extensions > Socket Server Plugin

    • You should see a Socket Server Control dialog window. Click Start Server.

Claude Desktop Configuration

To configure Claude Desktop, you need to modify its configuration file:

  1. Open the Configuration File:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • Alternatively, use the Settings menu in Claude Desktop (Settings > Developer > Edit Config).

  2. Add MCP Server Configuration: For development/unpublished server, add the following configuration:

    "mcpServers": {
      "cinema4d": {
        "command": "python3",
        "args": ["/Users/username/cinema4d-mcp/main.py"]
      }
    }
  3. Restart Claude Desktop after updating the configuration file.

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

Usage

  1. Ensure the Cinema 4D Socket Server is running.

  2. Open Claude Desktop and look for the hammer icon ๐Ÿ”จ in the input box, indicating MCP tools are available.

  3. Use the available Tool Commands to interact with Cinema 4D through Claude.

Agent Skill

If you use agent skills, the maintained companion skill for this MCP lives in vladmdgolam/agent-skills.

The skill captures production-oriented guidance that sits on top of the raw MCP tools, including:

  • when to prefer inspect_redshift_materials over ad-hoc Python for Redshift inspection

  • when to fall back to execute_python_script for full C4D API access

  • current Redshift limits when the runtime or node space is unavailable

  • practical MoGraph extraction and debugging workflows

Testing

Command Line Testing

To test the Cinema 4D socket server directly from the command line:

python main.py

You should see output confirming the server's successful start and connection to Cinema 4D.

Testing with MCP Test Harness

The repository includes a simple test harness for running predefined command sequences:

  1. Test Command File (tests/mcp_test_harness.jsonl): Contains a sequence of commands in JSONL format that can be executed in order. Each line represents a single MCP command with its parameters.

  2. GUI Test Runner (tests/mcp_test_harness_gui.py): A simple Tkinter GUI for running the test commands:

    python tests/mcp_test_harness_gui.py

    The GUI allows you to:

    • Select a JSONL test file

    • Run the commands in sequence

    • View the responses from Cinema 4D

This test harness is particularly useful for:

  • Rapidly testing new commands

  • Verifying plugin functionality after updates

  • Recreating complex scenes for debugging

  • Testing compatibility across different Cinema 4D versions

Troubleshooting & Debugging

  1. Check the log files:

    tail -f ~/Library/Logs/Claude/mcp*.log
  2. Verify Cinema 4D shows connections in its console after you open Claude Desktop.

  3. Test the wrapper script directly:

    cinema4d-mcp-wrapper
  4. If there are errors finding the mcp module, install it system-wide:

    pip install mcp
  5. For advanced debugging, use the MCP Inspector:

    npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp

Project File Structure

cinema4d-mcp/
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ LICENSE
โ”œโ”€โ”€ README.md
โ”œโ”€โ”€ main.py
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ setup.py
โ”œโ”€โ”€ bin/
โ”‚   โ””โ”€โ”€ cinema4d-mcp-wrapper
โ”œโ”€โ”€ c4d_plugin/
โ”‚   โ””โ”€โ”€ mcp_server_plugin.pyp
โ”œโ”€โ”€ src/
โ”‚   โ””โ”€โ”€ cinema4d_mcp/
โ”‚       โ”œโ”€โ”€ __init__.py
โ”‚       โ”œโ”€โ”€ server.py
โ”‚       โ”œโ”€โ”€ config.py
โ”‚       โ””โ”€โ”€ utils.py
โ””โ”€โ”€ tests/
    โ”œโ”€โ”€ test_server.py
    โ”œโ”€โ”€ mcp_test_harness.jsonl
    โ””โ”€โ”€ mcp_test_harness_gui.py

Tool Commands

General Scene & Execution

  • get_scene_info: Get summary info about the active Cinema 4D scene. โœ…

  • list_objects: List all scene objects (with hierarchy). โœ…

  • group_objects: Group selected objects under a new null. โœ…

  • execute_python: Execute custom Python code inside Cinema 4D. โœ…

  • save_scene: Save the current Cinema 4D project to disk. โœ…

  • load_scene: Load a .c4d file into the scene. โœ…

  • set_keyframe: Set a keyframe on an objects property (position, rotation, etc.). โœ…

Object Creation & Modification

  • add_primitive: Add a primitive (cube, sphere, cone, etc.) to the scene. โœ…

  • modify_object: Modify transform or attributes of an existing object. โœ…

  • create_abstract_shape: Create an organic, non-standard abstract form. โœ…

Cameras & Animation

  • create_camera: Add a new camera to the scene. โœ…

  • animate_camera: Animate a camera along a path (linear or spline-based). โœ…

Lighting & Materials

  • create_light: Add a light (omni, spot, etc.) to the scene. โœ…

  • create_material: Create a standard Cinema 4D material. โœ…

  • apply_material: Apply a material to a target object. โœ…

  • apply_shader: Generate and apply a stylized or procedural shader. โœ…

Redshift Support

  • inspect_redshift_materials: Read-only Redshift inspector with fallbacks for assignments, preview colors, readable params, a renderEngine-style node-material probe, and a Redshift GraphView fallback via redshift.GetRSMaterialNodeMaster(...). โœ… Known quirk: the top-level capabilities.redshift_module_available flag can still be false on some builds even when the per-material GraphView fallback succeeds. Treat each material's graph.backend and graph.graphview.redshift_module_imported as the authoritative signal.

  • validate_redshift_materials: Check Redshift material setup and connections. โœ… โš ๏ธ (Redshift materials not fully implemented)

MoGraph & Fields

  • create_mograph_cloner: Add a MoGraph Cloner (linear, radial, grid, etc.). โœ…

  • add_effector: Add a MoGraph Effector (Random, Plain, etc.). โœ…

  • apply_mograph_fields: Add and link a MoGraph Field to objects. โœ…

Dynamics & Physics

  • create_soft_body: Add a Soft Body tag to an object. โœ…

  • apply_dynamics: Apply Rigid or Soft Body physics. โœ…

Rendering & Preview

  • render_frame: Render a frame and save it to disk (file-based output only). โš ๏ธ (Works, but fails on large resolutions due to MemoryError: Bitmap Init failed. This is a resource limitation.)

  • render_preview: Render a quick preview and return base64 image (for AI). โœ…

  • snapshot_scene: Capture a snapshot of the scene (objects + preview image). โœ…

Compatibility Plan & Roadmap

Cinema 4D Version

Python Version

Compatibility Status

Notes

R21 / S22

Python 2.7

โŒ Not supported

Legacy API and Python version too old

R23

Python 3.7

๐Ÿ” Not planned

Not currently tested

S24 / R25 / S26

Python 3.9

โš ๏ธ Possible (TBD)

Requires testing and fallbacks for missing APIs

2023.0 / 2023.1

Python 3.9

๐Ÿงช In progress

Targeting fallback support for core functionality

2023.2

Python 3.10

๐Ÿงช In progress

Aligns with planned testing base

2024.0

Python 3.11

โœ… Supported

Verified

2025.0+

Python 3.11

โœ… Fully Supported

Primary development target

Compatibility Goals

  • Short Term: Ensure compatibility with C4D 2023.1+ (Python 3.9 and 3.10)

  • Mid Term: Add conditional handling for missing MoGraph and Field APIs

  • Long Term: Consider optional legacy plugin module for R23โ€“S26 support if demand arises

Recent Fixes

  • Context Awareness: Implemented robust object tracking using GUIDs. Commands creating objects return context (guid, actual_name, etc.). Subsequent commands correctly use GUIDs passed by the test harness/server to find objects reliably.

  • Object Finding: Reworked find_object_by_name to correctly handle GUIDs (numeric string format), fixed recursion errors, and improved reliability when doc.SearchObject fails.

  • GUID Detection: Command handlers (apply_material, create_mograph_cloner, add_effector, apply_mograph_fields, set_keyframe, group_objects) now correctly detect if identifiers passed in various parameters (object_name, target, target_name, list items) are GUIDs and search accordingly.

  • create_mograph_cloner: Fixed AttributeError for missing MoGraph parameters (like MG_LINEAR_PERSTEP) by using getattr fallbacks. Fixed logic bug where the found object wasn't correctly passed for cloning.

  • Rendering: Fixed TypeError in render_frame related to doc.ExecutePasses. snapshot_scene now correctly uses the working base64 render logic. Large render_frame still faces memory limits.

  • Registration: Fixed AttributeError for c4d.NilGuid.

Available Tools

25 tools
add_effectorC
Add a MoGraph Effector to the scene.

Args:
    effector_type: Type of effector (random, shader, field)
    name: Optional name for the effector
    target: Optional target object (e.g., cloner) to apply the effector to

Inputs: effector_type (required), name, target.

add_primitiveB
Add a primitive object to the Cinema 4D scene.

Args:
    primitive_type: Type of primitive (cube, sphere, cone, cylinder, plane, etc.)
    name: Optional name for the new object
    position: Optional [x, y, z] position
    size: Optional [x, y, z] size or dimensions

Inputs: primitive_type (required), name, position, size.

animate_cameraC
Create a camera animation.

Args:
    animation_type: Type of animation (wiggle, orbit, spline, linear)
    camera_name: Optional name of camera to animate
    positions: Optional list of [x,y,z] camera positions for keyframes
    frames: Optional list of frame numbers for keyframes

Inputs: animation_type (required), camera_name, positions, frames.

apply_dynamicsC
Add dynamics (rigid or soft) to the specified object.

Args:
    object_name: Name of the object to apply dynamics to
    dynamics_type: Type of dynamics to apply (rigid, soft)

Inputs: object_name (required), dynamics_type (required).

apply_materialC
Apply a material to an object.

Args:
    material_name: Name of the material to apply
    object_name: Name of the object to apply the material to

Inputs: material_name (required), object_name (required).

apply_mograph_fieldsC
Create and apply a MoGraph Field.

Args:
    field_type: Type of field (spherical, box, cylindrical, linear, radial, noise)
    target: Optional target object to apply the field to
    field_name: Optional name for the field
    parameters: Optional parameters for the field (strength, falloff)

Inputs: field_type (required), target, field_name, parameters.

apply_shaderC
Create and apply a specialized shader material.

Args:
    shader_type: Type of shader (noise, gradient, fresnel, etc)
    material_name: Optional name of material to apply shader to
    object_name: Optional name of object to apply the material to

Inputs: shader_type (required), material_name, object_name.

create_abstract_shapeC
Create an organic, abstract shape.

Args:
    shape_type: Type of shape (blob, metaball)
    name: Optional name for the shape

Inputs: shape_type (required), name.

create_cameraC
Create a new camera in the scene.

Args:
    name: Optional name for the new camera.
    position: Optional [x, y, z] position.
    properties: Optional dictionary of camera properties (e.g., {"focal_length": 50}).

Inputs: name, position, properties.

create_lightC
Add a light to the scene.

Args:
    light_type: Type of light (area, dome, spot)
    name: Optional name for the light

Inputs: light_type (required), name.

create_materialB
Create a new material in Cinema 4D.

Args:
    name: Name for the new material
    color: Optional [R, G, B] color (values 0-1)
    properties: Optional additional material properties

Inputs: name (required), color, properties.

create_mograph_clonerC
Create a MoGraph Cloner object of specified type.

Args:
    cloner_type: Type of cloner (grid, radial, linear)
    name: Optional name for the cloner

Inputs: cloner_type (required), name.

create_soft_bodyC
Add soft body dynamics to the specified object.

Args:
    object_name: Name of the object to convert to a soft body

Inputs: object_name (required).

execute_python_scriptA
Execute a Python script in Cinema 4D's Python environment.

This is the most reliable tool for non-trivial operations โ€” it gives full access
to the c4d API and avoids wrapper/schema mismatches that can affect other tools.

Args:
    script: Python code to execute in Cinema 4D. Has access to `c4d` and
        `c4d.modules.mograph` modules.

Important usage notes:
    - For animated/MoGraph data, always call doc.ExecutePasses() after SetTime():
        doc.SetTime(c4d.BaseTime(frame, fps))
        doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE)
    - For MoGraph/effector data, iterate frames sequentially (0..N) rather than
      jumping directly to a later frame โ€” sequential stepping produces more
      faithful results.
    - Security restrictions block certain keywords: import os, subprocess, exec(, eval(.
      Keep scripts within the c4d API surface.
    - For heavy operations (dense frame loops, complex MoGraph scenes), split work
      into multiple smaller scripts rather than one large monolith.
    - Use print() to return results โ€” output is captured and returned.

Inputs: script (required).

get_scene_infoB

Get information about the current Cinema 4D scene.

Inputs: no named parameters.

group_objectsC
Group multiple objects under a null object.

Args:
    object_names: List of object names to group
    group_name: Optional name for the group

Inputs: object_names (required), group_name.

inspect_redshift_materialsA
Inspect Redshift materials with best-effort fallbacks.

This tool is read-only and is designed to be useful even when the Redshift
Python runtime is unavailable. It can still report names, assignments,
preview-derived colors, readable description/container fields, and will
attempt graph inspection only when Cinema 4D exposes that data.

Args:
    material_name: Optional material name filter
    include_assignments: Include texture-tag assignments in the scene
    include_preview: Include sampled preview bitmap color data
    include_description: Include readable description entries
    include_container: Include safe BaseContainer values
    include_graph: Attempt node-graph inspection when available

Inputs: material_name, include_assignments, include_preview, include_description, +2 more.

list_objectsA

List all objects in the current Cinema 4D scene.

If this tool returns a validation error, use execute_python_script as a fallback
to traverse the object hierarchy manually via the c4d API.

Inputs: no named parameters.

load_sceneC
Load a Cinema 4D scene file.

Args:
    file_path: Path to the scene file to load

Inputs: file_path (required).

modify_objectC
Modify properties of an existing object.

Args:
    object_name: Name of the object to modify
    properties: Dictionary of properties to modify (position, rotation, scale, etc.)

Inputs: object_name (required), properties (required).

render_frameC
Render the current frame.

Args:
    output_path: Optional path to save the rendered image
    width: Optional render width in pixels
    height: Optional render height in pixels

Inputs: output_path, width, height.

render_previewB
Render the current view and return a base64-encoded preview image.

Args:
    width: Optional preview width in pixels
    height: Optional preview height in pixels
    frame: Optional frame number to render

Inputs: width, height, frame.

save_sceneB
Save the current Cinema 4D scene.

Args:
    file_path: Optional path to save the scene to

Inputs: file_path.

set_keyframeC
Set a keyframe for an object property.

Args:
    object_name: Name of the object
    property_name: Name of the property to keyframe (e.g., 'position.x')
    value: Value to set at the keyframe
    frame: Frame number to set the keyframe at

Inputs: object_name (required), property_name (required), value (required), frame (required).

snapshot_sceneB
Create a snapshot of the current scene state.

Args:
    file_path: Optional path to save the snapshot
    include_assets: Whether to include external assets in the snapshot

Inputs: file_path, include_assets.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.2/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific Cinema 4D operations like adding objects, applying materials, or rendering. However, some overlap exists between 'apply_dynamics' and 'create_soft_body' (both handle dynamics), and 'apply_material' vs 'apply_shader' (both apply materials), which could cause minor confusion despite clear descriptions.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as 'add_effector', 'create_camera', 'apply_material', and 'render_frame'. All tools use snake_case with clear, descriptive verbs, making the set predictable and easy to navigate.

    Tool Count3/5

    With 25 tools, the count is borderline high for a single server, potentially overwhelming for agents. While Cinema 4D is a complex application, the toolset feels heavy and might benefit from consolidation or categorization to improve usability without sacrificing functionality.

    Completeness5/5

    The toolset provides comprehensive coverage for 3D scene creation and manipulation in Cinema 4D, including object creation, material application, animation, rendering, and scene management. Key workflows like CRUD for objects, materials, and cameras are fully supported, with no apparent gaps that would hinder agent operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Connects Cinema 4D to Claude so users can create and manipulate 3D scenes through natural-language prompts. It supports object and primitive creation, cameras and animation, lighting, materials and shaders, MoGraph cloners and fields, dynamics, Redshift material inspection, plus rendering and scene previews.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Connects Cinema 4D to Claude so users can create and manipulate 3D scenes through natural-language prompts, covering primitives, objects, cameras, animations, lights, materials and shaders, Redshift inspection, MoGraph cloners and fields, dynamics, and frame or preview rendering. Custom Python execution inside Cinema 4D is also exposed for advanced workflows.
      -