Cascadeur MCP

An experimental Python bridge that lets MCP clients inspect and edit animation inside a running Cascadeur instance, without Computer Use.

MCP client → official MCP Python SDK (stdio)
           → private local JSON queue
           → Cascadeur main-thread bridge → native scene APIs

Features

• Scene/object inspection, frame access, and bounded Joint transform operations.

• Character skeleton inspection and a validated Cascy semantic rig profile.

• Named pelvis, chest, head, hand, elbow, foot and knee controls. Rig Point targets are writable; driven Joint transforms remain read-only in this profile.

• set_pose_sequence: up to eight existing frames in one checked transaction, with automatic rollback on failure.

• Session snapshots and a durable, single-pose JSON snapshot format.

• Native playback observation, bounded retiming, scene-copy saving and FBX export with a native license-entitlement check.

Related MCP server: blender-server-mcp-docker

Status and requirements

Alpha research prototype, not a general production animation SDK. Local development validation used Windows, Cascadeur 2026.2.2 and Python 3.12. Validation has only been performed on the developer's local machine. Cascadeur host connection on other machines has NOT been verified. A clean virtual-environment installation test on that same machine does not establish cross-machine host compatibility. The external package requires Python 3.10+ and the official MCP Python SDK v1. Other operating systems, Cascadeur releases and arbitrary character rigs have not been validated. MCP protocol compatibility is not client acceptance testing.

Cascadeur must be installed and running, with a compatible scene open. FBX export requires an eligible license. This repository contains no Cascadeur binaries, API stubs, character assets, game files, reference videos or audio. Obtain any required assets directly from their owners under their own terms.

Installation

On a new Windows machine, install Python 3.12 (including the Python launcher), Git, and Cascadeur separately. Download or clone this repository and open PowerShell in the extracted repository root (the directory containing pyproject.toml). Internet access is needed to obtain Python dependencies. No files from the original developer's machine are required.

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

Install the host hook separately:

1. Close Cascadeur normally after saving your scenes.

2. Copy cascadeur_scripts/c01_startup.py to <Cascadeur>/resources/scripts/python/events/application_started/c01_startup.py. Do not overwrite an unrelated existing script.

3. In that installed copy, replace "__C01_PROJECT_SOURCE__" with a Python string literal for this checkout's absolute src directory. Generate the correctly escaped value from the checkout root with:

   .\.venv\Scripts\python.exe -c "from pathlib import Path; print(repr(str(Path('src').resolve())))"

   Paste the entire printed quoted value after PROJECT_SOURCE =. The Cascadeur installation directory may require administrator write access.

4. Start Cascadeur and wait for startup to complete. The hook schedules the bridge on Cascadeur's Qt main thread.

Do not install the external MCP SDK or a replacement Qt runtime into Cascadeur. Keep the checkout at the configured path. An application update may require reinstalling the hook. To uninstall, close Cascadeur and remove only this hook.

Usage

Start with the read-only Codex configuration in examples/codex.toml. Replace its Python path with your virtual environment's absolute path. Obtain that path with (Resolve-Path .\.venv\Scripts\python.exe).Path, keeping the TOML single quotes around it. Add the sample table to your client's MCP configuration; do not overwrite unrelated existing settings. It launches:

<checkout>/.venv/Scripts/python.exe -m cascadeur_mcp.server

Other MCP clients can launch the same stdio command; their configuration syntax and end-to-end behavior have not been validated here. For advanced editing, deliberately enable the relevant tools in your client and use disposable scenes.

Run the read-only smoke client against the running host:

.\.venv\Scripts\python.exe examples\smoke_client.py --output evidence\local\smoke.json

Success requires all_tools_succeeded: true and real scene information in the response. The smoke output contains local runtime information and stays ignored. If the host is unavailable, check the hook's source path, restart Cascadeur, open a scene and confirm matching instance names. An installed Python package alone does not provide a running Cascadeur host.

A typical editing sequence is:

1. ping_cascadeur() and get_scene_info() to verify the live host.

2. list_characters() to discover current scene and character IDs.

3. get_rig_semantics(character_id) and get_semantic_pose(character_id, frame).

4. Save a native scene copy, then submit the named Point targets through set_pose_sequence(scene_id, character_id, poses).

5. Read the solved results and inspect real playback before accepting changes.

Discover full signatures with MCP tools/list; do not reuse stale IDs or assume that every tool accepts the same arguments. A semantic direction, orientation or bend value is a world-position Point target, not an Euler rotation.

Safety and limitations

• Fixed operation allowlist, strict finite-value validation and bounded payloads. No arbitrary shell, Python execution or generic menu-action tool is exposed.

• The private queue defaults to %LOCALAPPDATA%\cascadeur-mcp\c01 on Windows. Windows ACLs restrict it to the owner and SYSTEM. Authentication does not protect against malicious code running as the same OS user.

• Host and client must use the same CASCADEUR_MCP_INSTANCE if changed from c01.

• Character operations address existing frames in a bounded clip (at most 121 stored frames). Sequence writes do not extend the timeline.

• Snapshots and native Undo history are bounded. At the 16-character-snapshot session limit, save and restart; do not bypass the guard.

• Durable JSON snapshots restore one pose, not an entire animation. Use native .casc copies for full-scene recovery. Avoid concurrent manual/agent editing.

• A write timeout is an unknown outcome. Read back before retrying.

• FBX export currently accepts the full stored range of one supported character. It saves a new native copy first. Replacing an existing FBX requires its SHA-256.

• AutoPhysics/AutoPosing automation, arbitrary rigs, headless Cascadeur and a bundled Unity/game pipeline are not provided.

Development and verification

src/cascadeur_mcp contains the server, schemas and host adapters. tests covers protocol, validation and recovery-related guards. Its semantic fixture uses invented IDs and no geometry or vendor scene data. These tests are not a substitute for real Cascadeur playback, export or visual animation validation.

Local development experiments have exercised real character editing, playback and FBX/Unity round trips. Private captures, scene dumps and game/reference assets are intentionally excluded from this source release. See API provenance for adapter scope and source references.

License

MIT applies to this project's original source. Cascadeur and any third-party applications, assets or dependencies retain their own licenses. This is an independent project, not an official Cascadeur integration.