Cinema 4D MCP server

Cinema4D MCP Server connects Cinema 4D to Claude, enabling prompt-assisted 3D manipulation. This server acts as a bridge between Claude AI and Cinema 4D, allowing you to control your 3D environment through natural language prompts.

Prerequisites

• Cinema 4D (R2024+ recommended)
• Python 3.10 or higher (for the MCP Server component)

Installation

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

1. Copy the Plugin File to Cinema 4D's plugin folder:

   • 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
   • Click Start Server in the Socket Server Control dialog window

Claude Desktop Configuration

1. Open the Configuration File:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Or use Settings > Developer > Edit Config in Claude Desktop

2. Add MCP Server Configuration:

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

3. Restart Claude Desktop after saving the configuration

Usage

1. Start Cinema 4D and ensure the Socket Server is running
2. Open Claude Desktop and look for the hammer icon 🔨 in the input box (indicates MCP tools are available)
3. Use the available tool commands to interact with Cinema 4D through Claude

Testing

Command Line Testing

Test the Cinema 4D socket server directly:

python main.py

Testing with MCP Test Harness

Run the GUI test runner:

python tests/mcp_test_harness_gui.py

The GUI allows you to:

• Select a JSONL test file
• Run commands in sequence
• View responses from Cinema 4D

Troubleshooting & Debugging

• Check log files:

  tail -f ~/Library/Logs/Claude/mcp*.log
  

• Verify Cinema 4D shows connections in its console after opening 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
  

Available Tool Commands

General Scene Commands

• 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 object's property

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

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

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_preview: Render a quick preview and return base64 image
• snapshot_scene: Capture a snapshot of the scene (objects + preview image)

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.