Mcp4d

MCP4D -- Cinema 4D Bridge for Claude Code

A native C++ Cinema 4D plugin that connects Claude Code to Cinema 4D via the Model Context Protocol. Read the scene, build geometry, execute Python, cast rays, capture the viewport, all from your terminal.

Claude Code CLI
  └── Python MCP Server (stdio, thin adapter)
        └── TCP localhost:5555
              └── C4D C++ Plugin (.xdl64)

What It Does

Claude Code gains full access to Cinema 4D through 15 native commands:

| Category | Commands | |----------|----------| | Scene | ping, get_scene_info, get_object_info, list_materials | | Python | execute_python -- run arbitrary code in C4D's Python VM | | Raycasting | raycast -- screen-to-world hit testing | | Surface Rect | define_surface_rect, get_surface_rect, clear_surface_rect | | Native Ops | boolean, current_state_to_object, select_polys_at_rect | | Import | import_mesh -- OBJ, FBX, GLB, STL, USD | | Viewport | capture_viewport -- PNG snapshot with camera data |

The execute_python relay is the escape hatch. Anything that doesn't have a dedicated native command can be done through C4D's Python API. Native commands exist where Python is unreliable (booleans, CSTO) or where C++ is significantly better (scene traversal, raycasting, viewport capture).

Surface Rectangle Tool

An interactive viewport tool (Extensions > Surface Rectangle) that lets you click and drag on any polygon surface to define a rectangle. The rect data is shared with MCP -- draw interactively in the viewport, then read it programmatically from Claude Code.

Used for placing imported meshes, selecting polygon regions, and defining areas of interest on surfaces.

Recipes and Skills

The plugin ships with a recipe system in SKILLS.md that gives Claude Code ready-made workflows for common scene types. When you describe what you want (e.g. "dark moody product shot" or "exploded technical view"), Claude matches your description to a recipe and follows it step by step.

Current recipes include:

• clean-product-hero -- white studio, dramatic lighting, beauty shot setup
• dark-moody-tech -- dark background with colored accent lighting for electronics and tech products
• exploded-technical -- engineering-style exploded view with clean white background
• tech-collage-cluster -- dense vertical cluster of tech slabs, editorial style, procedural textures

You can also reference a recipe by name ("build a tech-collage-cluster") and Claude will follow it exactly.

Teach how you work

You can also teach Claude Code new recipes by walking it through your workflow step by step. It learns from your actions and saves them as reusable recipes so you don't have to repeat yourself. Even better; ask Claude Code to generate Python Extensions with dynamic fields so the back-and-forth becomes a single click.

Beyond recipes, SKILLS.md includes utility skills like polygon counting, texture size auditing, and batch deletion tools that Claude uses automatically when relevant.

Reference Documents

The repo includes compiled reference docs that Claude reads before working with specific renderers or APIs. These contain verified IDs, parameter values, and code patterns so Claude doesn't have to guess or look things up at runtime:

| File | Contents | |------|----------| | C4D_PYTHON_REFERENCE.md | Common C4D Python methods, constants, modeling commands | | OCTANE_REFERENCE.md | Octane material IDs, texture node wiring, light parameters, render settings | | REDSHIFT_REFERENCE.md | Redshift node material setup, shader graph construction | | INSYDIUM_REFERENCE.md | X-Particles and related Insydium plugin references |

These files are part of the agent's working knowledge. You don't need to read them yourself, but you can update them if you discover new IDs or patterns.

Requirements

• Cinema 4D 2024 or newer
• Python 3.10 or newer (usually already installed with C4D)
• Windows (macOS and Linux builds are defined in the project but untested)
• Claude Code CLI installed

Installation

Quick Install

Clone the repo, then run the installer script from its folder:

git clone https://github.com/cuneytozseker/mcp4d.git
cd mcp4d
python install.py

It will automatically find your Cinema 4D installation, copy the plugin, install the Python dependency, and register the MCP server with Claude Code. If you have multiple C4D versions installed, it will ask which one to use.

If automatic detection doesn't find your C4D, point it manually:

python install.py --c4d "C:/Program Files/Maxon Cinema 4D 2025"

Manual Installation

If you prefer to install manually, follow the steps below.

Step 1: Install the C4D Plugin

The compiled plugin is included in the dist/ folder of this repo:

dist/c4d-mcp-bridge.xdl64

Copy c4d-mcp-bridge.xdl64 into your Cinema 4D user plugins directory. The default location is:

C:\Users\\AppData\Roaming\Maxon\Maxon Cinema 4D 2025_XXXXXXXX\plugins\c4d-mcp-bridge\

To find your exact path, open Cinema 4D and go to Edit > Preferences > Open Preferences Folder. The plugins folder is inside there.

Create the c4d-mcp-bridge subfolder if it doesn't exist, and place the .xdl64 file inside it.

Restart Cinema 4D. You should see "MCP4D" in the Extensions menu if the plugin loaded correctly.

Step 2: Install the Python MCP Server

The MCP server is a small Python script that sits between Claude Code and the C4D plugin. It needs one dependency installed.

Open a terminal (Command Prompt, PowerShell, or your preferred terminal) and run:

pip install fastmcp

If you have multiple Python installations, make sure you're using Python 3.10+. You can check with python --version.

Step 3: Register the MCP Server with Claude Code

Tell Claude Code where to find the MCP server script. In your terminal, run:

claude mcp add cinema4d -- python "C:/path/to/c4d-mcp-bridge/mcp/server.py"

Replace C:/path/to/c4d-mcp-bridge/ with the actual path to this repo on your machine. Use forward slashes even on Windows.

Step 4: Verify the Connection

1. Make sure Cinema 4D is running with the plugin loaded
2. Open Claude Code in your terminal
3. Ask Claude to ping Cinema 4D:

> ping cinema 4d

If everything is connected, you'll get a {pong: true} response.

Optional: Auto-allow MCP Tools

By default, Claude Code will ask for your permission each time it wants to use a Cinema 4D tool. If you'd rather let it work without interruptions, create a file called .claude/settings.json in your project folder:

{
  "permissions": {
    "allow": [
      "mcp__cinema4d__*"
    ]
  }
}

This tells Claude Code to allow all Cinema 4D MCP tools without prompting.

Protocol

The TCP protocol is simple: newline-delimited JSON, one command per connection.

->  {"cmd": "ping"}
  {"cmd": "execute_python", "args": {"code": "print(c4d.GetC4DVersion())"}}
  {"cmd": "boolean", "args": {"object_a": "Cube", "object_b": "Sphere", "operation": "subtract"}}
<-  {"status": "ok", "data": {"name": "Cube", "points": 192, "polygons": 194}}

Project Structure

c4d-mcp-bridge/
├── source/                       # C++ plugin source
│   ├── main.cpp                  # Plugin entry, MessageData registration
│   ├── socket_server.cpp/.h      # Winsock2 TCP server, select() loop
│   ├── command_handler.cpp/.h    # JSON command dispatch
│   ├── scene_reader.cpp/.h       # get_scene_info, get_object_info, list_materials
│   ├── python_relay.cpp/.h       # execute_python via CPYTHON3VM
│   ├── raycaster.cpp/.h          # GeRayCollider screen-to-world raycasting
│   ├── viewport_capture.cpp/.h   # GetViewportImage to PNG
│   ├── surface_rect_tool.cpp/.h  # ToolData + viewport overlay + UI
│   ├── native_ops.cpp/.h         # Boolean, CSTO, SelectPolysAtRect
│   ├── mesh_import.cpp/.h        # MergeDocument + align to surface rect
│   ├── mcp4d_dialog.cpp/.h       # Plugin dialog UI
│   └── json.hpp                  # nlohmann/json (vendored)
├── project/
│   └── projectdefinition.txt     # C4D SDK build config
├── dist/
│   └── c4d-mcp-bridge.xdl64     # Pre-built plugin binary (Windows)
├── mcp/
│   ├── server.py                 # FastMCP stdio server (thin TCP adapter)
│   └── requirements.txt          # Python dependencies
├── install.py                    # Automated installer script
├── CLAUDE.md                     # Agent instructions and internal reference
├── SKILLS.md                     # Scene-building recipes and utility skills
├── C4D_PYTHON_REFERENCE.md       # C4D Python API quick reference
├── OCTANE_REFERENCE.md           # Octane Render IDs and patterns
├── REDSHIFT_REFERENCE.md         # Redshift node material reference
├── INSYDIUM_REFERENCE.md         # Insydium / X-Particles reference
└── README.md                     # This file

How It Works

1. The C++ plugin registers a MessageData hook that polls a TCP socket every 200ms on Cinema 4D's main thread.
2. The Python MCP server (server.py) runs as a stdio process managed by Claude Code. It translates MCP tool calls into JSON commands and forwards them over TCP to the plugin.
3. The command handler inside the plugin dispatches incoming JSON to the appropriate module: scene reader, Python relay, raycaster, and so on.
4. All C++ operations run on C4D's main thread (via the CoreMessage hook), ensuring thread safety with the scene graph.

Building from Source

If you want to modify the C++ plugin and compile it yourself, you'll need the Cinema 4D C++ SDK (R2024+) and CMake.

# From the Cinema 4D SDK root folder (the one containing "plugins/")
cmake --preset windows_vs2022_v143
cmake --build _build_v143 --target c4d-mcp-bridge --config Release

The build produces c4d-mcp-bridge.xdl64 at:

_build_v143/bin/Release/plugins/c4d-mcp-bridge/

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cuneytozseker
• Source: cuneytozseker/mcp4d
• License: MIT

Install and usage instructions live in the source repository linked above.