Clone the Repository

Skip to content

You signed in with another tab or window. Reload
to refresh your session. You signed out in another tab or window. Reload
to refresh your session. You switched accounts on another tab or window. Reload
to refresh your session. Dismiss alert

ttiimmaacc / cinema4d-mcp Public

• Notifications
  You must be signed in to change notification settings

• Fork 1

• Star 2

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

2 stars
1 fork
Branches
Tags
Activity

Star

Notifications
You must be signed in to change notification settings

ttiimmaacc/cinema4d-mcp

main

1 Branch
0 Tags

Go to file

Code

Folders and files

| Name | | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| Latest commit
-------------


ttiimmaacc

chore(.gitignore): update ignore list to prevent local files from bei…

Mar 26, 2025

565f0e3
 · Mar 26, 2025

History
-------

36 Commits

| | |
| bin | | bin | chore: update .gitignore to include additional Python and IDE files f… | Mar 14, 2025 |
| c4d_plugin | | c4d_plugin | chore(.gitignore): update ignore list to prevent local files from bei… | Mar 26, 2025 |
| src/cinema4d_mcp | | src/cinema4d_mcp | chore(.gitignore): update ignore list to prevent local files from bei… | Mar 26, 2025 |
| tests | | tests | chore(.gitignore): update ignore list to prevent local files from bei… | Mar 26, 2025 |
| .gitignore | | .gitignore | chore(.gitignore): update ignore list to prevent local files from bei… | Mar 26, 2025 |
| .python-version | | .python-version | ● first commit | Mar 13, 2025 |
| README.md | | README.md | docs(README): add compatibility plan and roadmap section to clarify s… | Mar 24, 2025 |
| main.py | | main.py | feat(README.md): update documentation to include new commands and rec… | Mar 17, 2025 |
| pyproject.toml | | pyproject.toml | feat(README.md): update documentation to include new commands and rec… | Mar 17, 2025 |
| setup.py | | setup.py | chore: update .gitignore to include additional Python and IDE files f… | Mar 14, 2025 |
| uv.lock | | uv.lock | ● first commit | Mar 13, 2025 |
| View all files | | |

Repository files navigation

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

• Development

• Troubleshooting & Debugging

• File Structure

• Tool Commands

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
• Python 3.10 or higher

Development 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 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\

   • 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).
   • Add MCP Server Configuration: For development/unpublished server, add the following configuration:

   json "mcpServers": { "cinema4d": { "command": "python3", "args": ["/Users/username/cinema4d-mcp/main.py"] } }

2. Restart Claude Desktop after updating the configuration file.

[TODO] For published server

{
  "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.

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:

   shell 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:

   shell 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:

   shell cinema4d-mcp-wrapper

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

   shell pip install mcp

5. For advanced debugging, use the MCP Inspector
   :

   shell 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

• validate_redshift_materials: Check Redshift material setup and connections.

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

• Fixed "Applied to: None" issue with MoGraph fields
  • Fixed field hierarchy by inserting directly under target object
  • Implemented proper Field Driver tag connection for Cinema 4D 2025.1
  • Added multiple field linkage approaches for maximum compatibility
  • Enabled 'Use Fields' checkbox using multiple parameter IDs
  • Fixed field visibility and parent-child relationship issues
• Fixed Grid Cloner creation issue by providing correct parameter IDs
• Fixed MoGraph Fields application by defining proper field type constants
• Improved hierarchical display in list_objects command
• Enhanced cloner visibility and creation reliability

About

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

Topics

cinema-4d
cinema-4d-plugin
claude-ai
ai-integration
mcp-server
maxon-cinema-pipeline

Resources

Readme

Activity

Stars

2 stars

Watchers

2 watching

Forks

1 fork

Report repository

Releases

No releases published

Packages 0

No packages published

Languages

• Python 99.5%

• Shell 0.5%

You can’t perform that action at this time.