Skip to content
Back to search

cinema4d-mcp

Cinema 4D plugin integrating Claude AI for prompt-driven 3D modeling, scene creation, and manipulation.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ttiimmaacc--cinema4d-mcp/badge.svg)](/listings/ttiimmaacc--cinema4d-mcp)

HTML

<a href="/listings/ttiimmaacc--cinema4d-mcp"><img src="/api/listings/ttiimmaacc--cinema4d-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 291 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Cinema4D MCP — Model Context Protocol (MCP) Server
  2. Cinema4D MCP Server connects Cinema 4D to Claude, enabling prompt-assisted 3D manipulation.
  3. ## Table of Contents
  4. - [Components](#components)
  5. - [Prerequisites](#prerequisites)
  6. - [Installation](#installation)
  7. - [Setup](#setup)
  8. - [Usage](#usage)
  9. - [Agent Skill](#agent-skill)
  10. - [Development](#development)
  11. - [Troubleshooting & Debugging](#troubleshooting--debugging)
  12. - [File Structure](#file-structure)
  13. - [Tool Commands](#tool-commands)
  14. - [Usage Guide](docs/USAGE_GUIDE.md) — practical tips, extraction patterns, and known issues
  15. ## Components
  16. 1. **C4D Plugin**: A socket server that listens for commands from the MCP server and executes them in the Cinema 4D environment.
  17. 2. **MCP Server**: A Python server that implements the MCP protocol and provides tools for Cinema 4D integration.
  18. ## Prerequisites
  19. - Cinema 4D (R2024+ recommended)
  20. - Python 3.10 or higher (for the MCP Server component)
  21. ## Installation
  22. To install the project, follow these steps:
  23. ### Clone the Repository
  24. ```bash
  25. git clone https://github.com/ttiimmaacc/cinema4d-mcp.git
  26. cd cinema4d-mcp
  27. ```
  28. ### Install the MCP Server Package
  29. ```bash
  30. pip install -e .
  31. ```
  32. ### Make the Wrapper Script Executable
  33. ```bash
  34. chmod +x bin/cinema4d-mcp-wrapper
  35. ```
  36. ## Setup
  37. ### Cinema 4D Plugin Setup
  38. To set up the Cinema 4D plugin, follow these steps:
  39. 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:
  40. - macOS: `/Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/`
  41. - Windows: `C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\`
  42. 2. **Start the Socket Server**:
  43. - Open Cinema 4D.
  44. - Go to Extensions > Socket Server Plugin
  45. - You should see a Socket Server Control dialog window. Click Start Server.
  46. ### Claude Desktop Configuration
  47. To configure Claude Desktop, you need to modify its configuration file:
  48. 1. **Open the Configuration File**:
  49. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  50. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  51. - Alternatively, use the Settings menu in Claude Desktop (Settings > Developer > Edit Config).
  52. 2. **Add MCP Server Configuration**:
  53. For development/unpublished server, add the following configuration:
  54. ```json
  55. "mcpServers": {
  56. "cinema4d": {
  57. "command": "python3",
  58. "args": ["/Users/username/cinema4d-mcp/main.py"]
  59. }
  60. }
  61. ```
  62. 3. **Restart Claude Desktop** after updating the configuration file.
  63. <details>
  64. <summary>[TODO] For published server</summary>
  65. ```json
  66. {
  67. "mcpServers": {
  68. "cinema4d": {
  69. "command": "cinema4d-mcp-wrapper",
  70. "args": []
  71. }
  72. }
  73. }
  74. ```
  75. </details>
  76. ## Usage
  77. 1. Ensure the Cinema 4D Socket Server is running.
  78. 2. Open Claude Desktop and look for the hammer icon 🔨 in the input box, indicating MCP tools are available.
  79. 3. Use the available [Tool Commands](#tool-commands) to interact with Cinema 4D through Claude.
  80. ## Agent Skill
  81. If you use agent skills, the maintained companion skill for this MCP lives in [vladmdgolam/agent-skills](https://github.com/vladmdgolam/agent-skills/tree/main/skills/cinema4d-mcp).
  82. The skill captures production-oriented guidance that sits on top of the raw MCP tools, including:
  83. - when to prefer `inspect_redshift_materials` over ad-hoc Python for Redshift inspection
  84. - when to fall back to `execute_python_script` for full C4D API access
  85. - current Redshift limits when the runtime or node space is unavailable
  86. - practical MoGraph extraction and debugging workflows
  87. ## Testing
  88. ### Command Line Testing
  89. To test the Cinema 4D socket server directly from the command line:
  90. ```bash
  91. python main.py
  92. ```
  93. You should see output confirming the server's successful start and connection to Cinema 4D.
  94. ### Testing with MCP Test Harness
  95. The repository includes a simple test harness for running predefined command sequences:
  96. 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.
  97. 2. **GUI Test Runner** (`tests/mcp_test_harness_gui.py`): A simple Tkinter GUI for running the test commands:
  98. ```bash
  99. python tests/mcp_test_harness_gui.py
  100. ```
  101. The GUI allows you to:
  102. - Select a JSONL test file
  103. - Run the commands in sequence
  104. - View the responses from Cinema 4D
  105. This test harness is particularly useful for:
  106. - Rapidly testing new commands
  107. - Verifying plugin functionality after updates
  108. - Recreating complex scenes for debugging
  109. - Testing compatibility across different Cinema 4D versions
  110. ## Troubleshooting & Debugging
  111. 1. Check the log files:
  112. ```bash
  113. tail -f ~/Library/Logs/Claude/mcp*.log
  114. ```
  115. 2. Verify Cinema 4D shows connections in its console after you open Claude Desktop.
  116. 3. Test the wrapper script directly:
  117. ```bash
  118. cinema4d-mcp-wrapper
  119. ```
  120. 4. If there are errors finding the mcp module, install it system-wide:
  121. ```bash
  122. pip install mcp
  123. ```
  124. 5. For advanced debugging, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
  125. ```bash
  126. npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp
  127. ```
  128. ## Project File Structure
  129. ```
  130. cinema4d-mcp/
  131. ├── .gitignore
  132. ├── LICENSE
  133. ├── README.md
  134. ├── main.py
  135. ├── pyproject.toml
  136. ├── setup.py
  137. ├── bin/
  138. │ └── cinema4d-mcp-wrapper
  139. ├── c4d_plugin/
  140. │ └── mcp_server_plugin.pyp
  141. ├── src/
  142. │ └── cinema4d_mcp/
  143. │ ├── __init__.py
  144. │ ├── server.py
  145. │ ├── config.py
  146. │ └── utils.py
  147. └── tests/
  148. ├── test_server.py
  149. ├── mcp_test_harness.jsonl
  150. └── mcp_test_harness_gui.py
  151. ```
  152. ## Tool Commands
  153. ### General Scene & Execution
  154. - `get_scene_info`: Get summary info about the active Cinema 4D scene. ✅
  155. - `list_objects`: List all scene objects (with hierarchy). ✅
  156. - `group_objects`: Group selected objects under a new null. ✅
  157. - `execute_python`: Execute custom Python code inside Cinema 4D. ✅
  158. - `save_scene`: Save the current Cinema 4D project to disk. ✅
  159. - `load_scene`: Load a `.c4d` file into the scene. ✅
  160. - `set_keyframe`: Set a keyframe on an objects property (position, rotation, etc.). ✅
  161. ### Object Creation & Modification
  162. - `add_primitive`: Add a primitive (cube, sphere, cone, etc.) to the scene. ✅
  163. - `modify_object`: Modify transform or attributes of an existing object. ✅
  164. - `create_abstract_shape`: Create an organic, non-standard abstract form. ✅
  165. ### Cameras & Animation
  166. - `create_camera`: Add a new camera to the scene. ✅
  167. - `animate_camera`: Animate a camera along a path (linear or spline-based). ✅
  168. ### Lighting & Materials
  169. - `create_light`: Add a light (omni, spot, etc.) to the scene. ✅
  170. - `create_material`: Create a standard Cinema 4D material. ✅
  171. - `apply_material`: Apply a material to a target object. ✅
  172. - `apply_shader`: Generate and apply a stylized or procedural shader. ✅
  173. ### Redshift Support
  174. - `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(...)`. ✅
  175. 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.
  176. - `validate_redshift_materials`: Check Redshift material setup and connections. ✅ ⚠️ (Redshift materials not fully implemented)
  177. ### MoGraph & Fields
  178. - `create_mograph_cloner`: Add a MoGraph Cloner (linear, radial, grid, etc.). ✅
  179. - `add_effector`: Add a MoGraph Effector (Random, Plain, etc.). ✅
  180. - `apply_mograph_fields`: Add and link a MoGraph Field to objects. ✅
  181. ### Dynamics & Physics
  182. - `create_soft_body`: Add a Soft Body tag to an object. ✅
  183. - `apply_dynamics`: Apply Rigid or Soft Body physics. ✅
  184. ### Rendering & Preview
  185. - `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.)
  186. - `render_preview`: Render a quick preview and return base64 image (for AI). ✅
  187. - `snapshot_scene`: Capture a snapshot of the scene (objects + preview image). ✅
  188. ## Compatibility Plan & Roadmap
  189. | Cinema 4D Version | Python Version | Compatibility Status | Notes |
  190. | ----------------- | -------------- | -------------------- | ------------------------------------------------- |
  191. | R21 / S22 | Python 2.7 | ❌ Not supported | Legacy API and Python version too old |
  192. | R23 | Python 3.7 | 🔍 Not planned | Not currently tested |
  193. | S24 / R25 / S26 | Python 3.9 | ⚠️ Possible (TBD) | Requires testing and fallbacks for missing APIs |
  194. | 2023.0 / 2023.1 | Python 3.9 | 🧪 In progress | Targeting fallback support for core functionality |
  195. | 2023.2 | Python 3.10 | 🧪 In progress | Aligns with planned testing base |
  196. | 2024.0 | Python 3.11 | ✅ Supported | Verified |
  197. | 2025.0+ | Python 3.11 | ✅ Fully Supported | Primary development target |
  198. ### Compatibility Goals
  199. - **Short Term**: Ensure compatibility with C4D 2023.1+ (Python 3.9 and 3.10)
  200. - **Mid Term**: Add conditional handling for missing MoGraph and Field APIs
  201. - **Long Term**: Consider optional legacy plugin module for R23–S26 support if demand arises
  202. ## Recent Fixes
  203. - 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.
  204. - Object Finding: Reworked find_object_by_name to correctly handle GUIDs (numeric string format), fixed recursion errors, and improved reliability when doc.SearchObject fails.
  205. - 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.
  206. - 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.
  207. - 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.
  208. - Registration: Fixed AttributeError for c4d.NilGuid.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.