{"id":"c01cc4c6-05d0-4bc8-99df-2d713e0a0edd","slug":"cinema4d-mcp","kind":"mcp","name":"cinema4d-mcp","summary":"Cinema 4D plugin integrating Claude AI for prompt-driven 3D modeling, scene creation, and manipulation.","owner":"ttiimmaacc","repoUrl":"https://github.com/ttiimmaacc/cinema4d-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":132,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T03:44:09.091Z","logoUrl":"https://avatars.githubusercontent.com/u/9548950?u=d26ff88085f7623d555bd7d6ba271b22e5a32751&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","data-analytics","design-media"],"tags":["cinema-4d","cinema-4d-plugin","maxon-cinema-pipeline","ai-integration","claude-ai"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T04:12:07.303Z","sample":false,"url":"https://conduits.dev/tools/cinema4d-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"cinema4d-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Cinema4D MCP — Model Context Protocol (MCP) Server\n\nCinema4D MCP Server connects Cinema 4D to Claude, enabling prompt-assisted 3D manipulation.\n\n## Table of Contents\n\n- [Components](#components)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Setup](#setup)\n- [Usage](#usage)\n- [Agent Skill](#agent-skill)\n- [Development](#development)\n- [Troubleshooting & Debugging](#troubleshooting--debugging)\n- [File Structure](#file-structure)\n- [Tool Commands](#tool-commands)\n- [Usage Guide](docs/USAGE_GUIDE.md) — practical tips, extraction patterns, and known issues\n\n## Components\n\n1. **C4D Plugin**: A socket server that listens for commands from the MCP server and executes them in the Cinema 4D environment.\n2. **MCP Server**: A Python server that implements the MCP protocol and provides tools for Cinema 4D integration.\n\n## Prerequisites\n\n- Cinema 4D (R2024+ recommended)\n- Python 3.10 or higher (for the MCP Server component)\n\n## Installation\n\nTo install the project, follow these steps:\n\n### Clone the Repository\n\n```bash\ngit clone https://github.com/ttiimmaacc/cinema4d-mcp.git\ncd cinema4d-mcp\n```\n\n### Install the MCP Server Package\n\n```bash\npip install -e .\n```\n\n### Make the Wrapper Script Executable\n\n```bash\nchmod +x bin/cinema4d-mcp-wrapper\n```\n\n## Setup\n\n### Cinema 4D Plugin Setup\n\nTo set up the Cinema 4D plugin, follow these steps:\n\n1. **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:\n\n   - macOS: `/Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/`\n   - Windows: `C:\\Users\\USERNAME\\AppData\\Roaming\\Maxon\\Maxon Cinema 4D\\plugins\\`\n\n2. **Start the Socket Server**:\n   - Open Cinema 4D.\n   - Go to Extensions > Socket Server Plugin\n   - You should see a Socket Server Control dialog window. Click Start Server.\n\n### Claude Desktop Configuration\n\nTo configure Claude Desktop, you need to modify its configuration file:\n\n1. **Open the Configuration File**:\n\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - Alternatively, use the Settings menu in Claude Desktop (Settings > Developer > Edit Config).\n\n2. **Add MCP Server Configuration**:\n   For development/unpublished server, add the following configuration:\n   ```json\n   \"mcpServers\": {\n     \"cinema4d\": {\n       \"command\": \"python3\",\n       \"args\": [\"/Users/username/cinema4d-mcp/main.py\"]\n     }\n   }\n   ```\n3. **Restart Claude Desktop** after updating the configuration file.\n<details>\n\n  <summary>[TODO] For published server</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"cinema4d\": {\n      \"command\": \"cinema4d-mcp-wrapper\",\n      \"args\": []\n    }\n  }\n}\n```\n\n   </details>\n\n## Usage\n\n1. Ensure the Cinema 4D Socket Server is running.\n2. Open Claude Desktop and look for the hammer icon 🔨 in the input box, indicating MCP tools are available.\n3. Use the available [Tool Commands](#tool-commands) to interact with Cinema 4D through Claude.\n\n## Agent Skill\n\nIf 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).\n\nThe skill captures production-oriented guidance that sits on top of the raw MCP tools, including:\n\n- when to prefer `inspect_redshift_materials` over ad-hoc Python for Redshift inspection\n- when to fall back to `execute_python_script` for full C4D API access\n- current Redshift limits when the runtime or node space is unavailable\n- practical MoGraph extraction and debugging workflows\n\n## Testing\n\n### Command Line Testing\n\nTo test the Cinema 4D socket server directly from the command line:\n\n```bash\npython main.py\n```\n\nYou should see output confirming the server's successful start and connection to Cinema 4D.\n\n### Testing with MCP Test Harness\n\nThe repository includes a simple test harness for running predefined command sequences:\n\n1. **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.\n\n2. **GUI Test Runner** (`tests/mcp_test_harness_gui.py`): A simple Tkinter GUI for running the test commands:\n\n   ```bash\n   python tests/mcp_test_harness_gui.py\n   ```\n\n   The GUI allows you to:\n\n   - Select a JSONL test file\n   - Run the commands in sequence\n   - View the responses from Cinema 4D\n\nThis test harness is particularly useful for:\n\n- Rapidly testing new commands\n- Verifying plugin functionality after updates\n- Recreating complex scenes for debugging\n- Testing compatibility across different Cinema 4D versions\n\n## Troubleshooting & Debugging\n\n1. Check the log files:\n\n   ```bash\n   tail -f ~/Library/Logs/Claude/mcp*.log\n   ```\n\n2. Verify Cinema 4D shows connections in its console after you open Claude Desktop.\n\n3. Test the wrapper script directly:\n\n   ```bash\n   cinema4d-mcp-wrapper\n   ```\n\n4. If there are errors finding the mcp module, install it system-wide:\n\n   ```bash\n   pip install mcp\n   ```\n\n5. For advanced debugging, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n   ```bash\n   npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp\n   ```\n\n## Project File Structure\n\n```\ncinema4d-mcp/\n├── .gitignore\n├── LICENSE\n├── README.md\n├── main.py\n├── pyproject.toml\n├── setup.py\n├── bin/\n│   └── cinema4d-mcp-wrapper\n├── c4d_plugin/\n│   └── mcp_server_plugin.pyp\n├── src/\n│   └── cinema4d_mcp/\n│       ├── __init__.py\n│       ├── server.py\n│       ├── config.py\n│       └── utils.py\n└── tests/\n    ├── test_server.py\n    ├── mcp_test_harness.jsonl\n    └── mcp_test_harness_gui.py\n```\n\n## Tool Commands\n\n### General Scene & Execution\n\n- `get_scene_info`: Get summary info about the active Cinema 4D scene. ✅\n- `list_objects`: List all scene objects (with hierarchy). ✅\n- `group_objects`: Group selected objects under a new null. ✅\n- `execute_python`: Execute custom Python code inside Cinema 4D. ✅\n- `save_scene`: Save the current Cinema 4D project to disk. ✅\n- `load_scene`: Load a `.c4d` file into the scene. ✅\n- `set_keyframe`: Set a keyframe on an objects property (position, rotation, etc.). ✅\n\n### Object Creation & Modification\n\n- `add_primitive`: Add a primitive (cube, sphere, cone, etc.) to the scene. ✅\n- `modify_object`: Modify transform or attributes of an existing object. ✅\n- `create_abstract_shape`: Create an organic, non-standard abstract form. ✅\n\n### Cameras & Animation\n\n- `create_camera`: Add a new camera to the scene. ✅\n- `animate_camera`: Animate a camera along a path (linear or spline-based). ✅\n\n### Lighting & Materials\n\n- `create_light`: Add a light (omni, spot, etc.) to the scene. ✅\n- `create_material`: Create a standard Cinema 4D material. ✅\n- `apply_material`: Apply a material to a target object. ✅\n- `apply_shader`: Generate and apply a stylized or procedural shader. ✅\n\n### Redshift Support\n\n- `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(...)`. ✅\n  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.\n- `validate_redshift_materials`: Check Redshift material setup and connections. ✅ ⚠️ (Redshift materials not fully implemented)\n\n### MoGraph & Fields\n\n- `create_mograph_cloner`: Add a MoGraph Cloner (linear, radial, grid, etc.). ✅\n- `add_effector`: Add a MoGraph Effector (Random, Plain, etc.). ✅\n- `apply_mograph_fields`: Add and link a MoGraph Field to objects. ✅\n\n### Dynamics & Physics\n\n- `create_soft_body`: Add a Soft Body tag to an object. ✅\n- `apply_dynamics`: Apply Rigid or Soft Body physics. ✅\n\n### Rendering & Preview\n\n- `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.)\n- `render_preview`: Render a quick preview and return base64 image (for AI). ✅\n- `snapshot_scene`: Capture a snapshot of the scene (objects + preview image). ✅\n\n## Compatibility Plan & Roadmap\n\n| Cinema 4D Version | Python Version | Compatibility Status | Notes                                             |\n| ----------------- | -------------- | -------------------- | ------------------------------------------------- |\n| R21 / S22         | Python 2.7     | ❌ Not supported     | Legacy API and Python version too old             |\n| R23               | Python 3.7     | 🔍 Not planned       | Not currently tested                              |\n| S24 / R25 / S26   | Python 3.9     | ⚠️ Possible (TBD)    | Requires testing and fallbacks for missing APIs   |\n| 2023.0 / 2023.1   | Python 3.9     | 🧪 In progress       | Targeting fallback support for core functionality |\n| 2023.2            | Python 3.10    | 🧪 In progress       | Aligns with planned testing base                  |\n| 2024.0            | Python 3.11    | ✅ Supported         | Verified                                          |\n| 2025.0+           | Python 3.11    | ✅ Fully Supported   | Primary development target                        |\n\n### Compatibility Goals\n\n- **Short Term**: Ensure compatibility with C4D 2023.1+ (Python 3.9 and 3.10)\n- **Mid Term**: Add conditional handling for missing MoGraph and Field APIs\n- **Long Term**: Consider optional legacy plugin module for R23–S26 support if demand arises\n\n## Recent Fixes\n\n- 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.\n- Object Finding: Reworked find_object_by_name to correctly handle GUIDs (numeric string format), fixed recursion errors, and improved reliability when doc.SearchObject fails.\n- 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.\n- 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.\n- 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.\n- Registration: Fixed AttributeError for c4d.NilGuid.\n"}