Cinema4D MCP — Model Context Protocol (MCP) Server
Cinema4D MCP Server connects Cinema 4D to Claude, enabling prompt-assisted 3D manipulation.
Table of Contents
- Components
- Prerequisites
- Installation
- Setup
- Usage
- Agent Skill
- Development
- Troubleshooting & Debugging
- File Structure
- Tool Commands
- Usage Guide — practical tips, extraction patterns, and known issues
Components
- C4D Plugin: A socket server that listens for commands from the MCP server and executes them in the Cinema 4D environment.
- 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:
-
Copy the Plugin File: Copy the
c4d_plugin/mcp_server_plugin.pypfile 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\
- macOS:
-
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:
-
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).
- macOS:
-
Add MCP Server Configuration: For development/unpublished server, add the following configuration:
"mcpServers": { "cinema4d": { "command": "python3", "args": ["/Users/username/cinema4d-mcp/main.py"] } } -
Restart Claude Desktop after updating the configuration file.
{
"mcpServers": {
"cinema4d": {
"command": "cinema4d-mcp-wrapper",
"args": []
}
}
}
Usage
- Ensure the Cinema 4D Socket Server is running.
- Open Claude Desktop and look for the hammer icon 🔨 in the input box, indicating MCP tools are available.
- 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_materialsover ad-hoc Python for Redshift inspection - when to fall back to
execute_python_scriptfor 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:
-
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. -
GUI Test Runner (
tests/mcp_test_harness_gui.py): A simple Tkinter GUI for running the test commands:python tests/mcp_test_harness_gui.pyThe 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
-
Check the log files:
tail -f ~/Library/Logs/Claude/mcp*.log -
Verify Cinema 4D shows connections in its console after you open Claude Desktop.
-
Test the wrapper script directly:
cinema4d-mcp-wrapper -
If there are errors finding the mcp module, install it system-wide:
pip install mcp -
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.c4dfile 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 viaredshift.GetRSMaterialNodeMaster(...). ✅ Known quirk: the top-levelcapabilities.redshift_module_availableflag can still befalseon some builds even when the per-material GraphView fallback succeeds. Treat each material'sgraph.backendandgraph.graphview.redshift_module_importedas 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
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.
