4DMCP

A local Model Context Protocol server for Cinema 4D. Inspect scenes, model and assemble objects, edit materials and animation, and verify results through scene readback and images.

Development preview · Apache 2.0 · Windows / Cinema 4D 2026.1

Full application coverage is still in progress. The coverage chart tracks all 33 feature families and separates verified workflows from remaining work.

Capabilities

• Scene hierarchy, transforms, parameters, selections, materials, dependencies and evaluated geometry.
• Polygon and spline modeling, generators, deformers, volumes, axes, cloning and scene assembly.
• UV coordinates, explicit normals, Phong smoothing and edge breaks.
• Evaluated snapshots capture bounded editable geometry at a requested frame, preserve the source, and retain the result's normal parent-relative behavior. See evaluated snapshots.
• Classic and Redshift material graphs, lights, cameras, render settings, previews and background render jobs.
• Animation, selected rigging and simulation operations, MoGraph, Fields, takes and node graphs.
• Local asset discovery/loading, document management, checkpoints and undo.
• Version-matched SDK symbol search and definition retrieval to help the agent use the installed API.

Support varies by operation. Query health, command.list and command.describe against the running host before editing. The current source's exact test counts and scoped native checks are recorded in verification.

How it works

flowchart LR
    A[MCP client] <-->|stdio| B[4DMCP server]
    B <-->|authenticated localhost socket| C[Cinema Python plugin]
    C --> D[Cinema main thread]
    D --> E[Scene readback and images]
    E --> A

Loading

The Python plugin runs SDK operations on Cinema's main thread. The MCP server uses one bounded socket connection per call. It can start before Cinema; calls report an unavailable host until the plugin is running.

Windows setup

Requirements: licensed Cinema 4D 2026.1, Python 3.10 or newer, and Git. Redshift workflows require a compatible installed Redshift version; validation used 2026.2.

git clone https://github.com/tenetmotion/4DMCP.git
cd 4DMCP
.\scripts\install.ps1 -PluginDirectory 'C:\path\to\your\Cinema-preferences\plugins'

Choose the plugins directory inside your Cinema preferences folder. The installer creates a project-local .venv, installs the Python package, backs up any existing bridge plugin and writes a local credential file. Restart Cinema after installation.

For manual Python setup:

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe scripts/install.py --plugin-directory 'C:\path\to\your\Cinema-preferences\plugins'

Connect an MCP client

Use the generated .local/codex.toml snippet for Codex, or configure another MCP client to run the absolute path to .venv/Scripts/4dmcp.exe with this repository as its working directory. It speaks MCP over stdio.

The compatibility entry points cinemamcp and python -m cinemamcp remain available. The plugin folder, credential directory, environment variables and workflow resource URIs also retain their existing names; see rename compatibility.

Optional native viewport capture

Render previews work through the Python adapter. Direct viewport capture additionally requires the C++ helper, the matching Maxon SDK, Visual Studio 2022 C++ Build Tools and the Windows SDK. SDK archives and compiled binaries are not included in this source repository.

The plugin currently uses development registration IDs. Use unique Maxon-issued IDs before redistributing a packaged plugin; this repository is a development source release.

Configuration and execution

The installer writes %USERPROFILE%/.cinemamcp/config.json; CINEMAMCP_CONFIG overrides its location. A nonempty authentication token is required. The bridge binds only to 127.0.0.1, using port 54321 by default.

Document guards prevent edits against a different active document. Entity IDs are valid only for the current Cinema process. A timeout does not cancel an SDK operation already running.

allow_python enables trusted Python execution inside Cinema. It is enabled by the installer, has the privileges of Cinema, and is not a sandbox. Set it to false for a deployment that should expose only the registered operations.

See usage, SDK reference setup, and the protocol contract.

Development

.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest -q

Automated SDK-independent tests run without Cinema. Native smoke scripts require Cinema and are separate from those tests. Local reports, scene files, credentials, caches and generated packages stay outside Git.

License

Apache License 2.0. See NOTICE. Cinema 4D and Redshift are separately licensed Maxon products; this is an independent project.