Skip to main content
Glama
Cascadeur MCP
by MnxD2A6

Cascadeur MCP

Alpha trial 0.5.0a13 includes opt-in complete sampled motion, native playback/visible range coverage, and persistent failed-recovery protection. See sampled motion and persistent recovery.

Download matching source and wheel packages from the a13 GitHub prerelease. Follow the Windows trial guide or the installation steps below. It is an Alpha, not a stable release. The earlier a11 wheel does not contain the a12/a13 features. For existing installations, follow upgrading. The package is not published to PyPI. Use the matching source/wheel, not a guessed pip install cascadeur-mcp command.

Version 0.5.0a13 adds persistent failed-recovery protection and read-only get_recovery_status(). Reopening a changed quarantine does not unlock writes; the complete recorded pre-failure checkpoint must match. This does not fix native shutdown or cover every mid-write crash. Upgrade/restart both peers for write contract revision 3. Other-machine host connection remains unverified.

Version 0.5.0a9 extends failed-character-recovery protection to every MCP write route on that scene, including legacy transforms, timeline, playback start and FBX export. Reads, owned playback stop and saving a new quarantine .casc remain available. This is a session-local guard, not a persistent/native UI lock. a9 introduced write contract revision 2; a13 now requires revision 3. Upgrade and restart both client and host. See recovery protection. Existing users should follow the upgrade checklist.

Version 0.5.0a8 adds a fail-closed safety restriction after native CLAMPED_BEZIER recovery failed: character Point and finger writes reject scenes containing that mode before editing. Retiming no longer accepts it. This does not repair Cascadeur Undo. Reads and the verified curve modes remain available.

Version 0.5.0a7 adds a semantic edit_impact report to curve-preserving offsets: direct edits and solver-coupled Points are grouped by body role and slot, using actual verified native targets. See edit-impact reports.

Version 0.5.0a6 adds offset_semantic_pose_sequence_preserving_curves: a separate existing-key edit that keeps track/key/interpolation/easing metadata and protects unedited baked tracks. See curve-preserving editing for its strict supported scope. Ordinary Point sequence writes retain their eight-frame limit. Native playback now sets both playback and visible timeline boundaries; see the sampled-motion notes below.

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

Use this bridge for structured inspection, batch pose corrections, supported retiming, checked recovery and licensed FBX delivery. It does not contain a video motion-capture backend or guarantee professional animation from a prompt. See the practical editing example and scope (中文), including the distinction between a successful tool call and visual animation quality.

  • get_bridge_capabilities: read the responding host's loaded bridge version, operation classifications, limits and restrictions without probing a rig or license.

  • get_character_edit_readiness: read scene/rig/track blockers and remaining snapshot/transaction capacity before three supported semantic Point edit policies. This advisory read allocates no history; real writes always recheck.

  • Structured execution errors alongside the existing text and MCP error flag, including unknown write outcomes and explicitly verified recovery states.

  • Bilateral write-contract checks: outdated or incompatible peers cannot write; existing read-only diagnostics remain usable with older protocol-1 hosts.

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

  • Optional role selection and joint-state omission in get_semantic_pose reduce unnecessary Transform reads and response data while retaining full rig validation.

  • get_semantic_pose_sequence: read up to eight existing frames once, with the same optional selection and actual native values.

  • offset_semantic_pose_sequence: translate whole named Point groups across up to eight frames once, from each frame's real current targets. Full capture, checked commit and rollback remain; this key-authoring operation uses LINEAR intervals and does not preserve authored easing. See batch workflow and limits.

  • set_pose_sequence: up to eight existing frames in one checked transaction, with guarded rollback attempts and explicit recovery-required errors.

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

  • get_recovery_status: read the persistent instance fence after an explicitly unverified character recovery. A changed quarantine remains blocked across restarts; only a matching complete pre-failure checkpoint permits write checks.

  • Validated Cascy finger-local read/write channels through get_hand_pose and set_hand_pose_sequence; hand Point targets alone do not make a fist.

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

  • Opt-in set_pose_sequence(..., sampled_motion=true) writes up to 64 complete, increasing semantic Point poses in one checked native transaction. It requires the full stored playback/visible range; ordinary calls remain limited to eight. Large skeleton reads can omit track section details with include_track_sections=false. See sampled motion and measured safety.

Related MCP server: Cascadeur MCP

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. Current source version: 0.5.0a13 (Alpha); write-contract revision: 3. 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.

Native shutdown stability remains under investigation. Local sessions have both exited normally and failed with 0xC0000005 in Qt6Core.dll after normal close requests. A no-MCP control reproduced the failure after a vendor-API save; this narrows the investigation but does not establish its root cause or prove MCP can never affect it. This alpha does not claim production-safe native shutdown across every workflow.

The GitHub workflow in .github/workflows/python-tests.yml is configured to run installation, Python contract/stdio tests, dependency checks and wheel-import checks on Windows and Linux with Python 3.10 and 3.12. Hosted CI does not install Cascadeur and does not establish native rig editing or another machine's host connection. Native curve validation is documented separately in curve-preserving editing.

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. Scene-dependent tools require a compatible open scene; ping and capability discovery do not. 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. Save scenes and close Cascadeur normally. Enter your actual installation folder, preview, then apply:

$cascadeurHome = Read-Host 'Enter your Cascadeur installation folder'
.\.venv\Scripts\python.exe -m cascadeur_mcp.manage install-host --cascadeur-home $cascadeurHome
.\.venv\Scripts\python.exe -m cascadeur_mcp.manage install-host --cascadeur-home $cascadeurHome --apply

This generates the source path safely and creates only the documented startup hook. An existing different hook returns HOOK_CONFLICT and remains untouched; there is no force overwrite. Write access may require administrator permissions. Then start Cascadeur and open a scene. The hook schedules the bridge on Cascadeur's Qt main thread. Check the connection:

.\.venv\Scripts\python.exe -m cascadeur_mcp.manage doctor --cascadeur-home $cascadeurHome --live --format text

See installation and diagnostics for instances, error codes, static checks, and exact-match uninstall. Without --apply, hook maintenance commands only preview. Without --live, doctor sends no requests.

Do not install the external MCP SDK or a replacement Qt runtime into Cascadeur. When upgrading, save scenes and exit Cascadeur normally, update the package, then restart both Cascadeur and the external MCP server. A cached old host or client will be refused for writes. The write contract compares protocol, semantic revision and write schemas; matching package version strings alone are not proof of compatibility. See capabilities and errors. Keep the checkout at the configured path. An application update may require reinstalling the hook. Close Cascadeur before using uninstall-host --apply.

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. get_bridge_capabilities() to read the loaded host contract, then ping_cascadeur() and get_scene_info() to check the host and active scene.

  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 and rediscover its scene ID. Inspect prerequisites with get_character_edit_readiness, then submit the named Point targets through set_pose_sequence(scene_id, character_id, poses). A passed preflight does not validate new targets or guarantee a successful write.

  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.

Capability read/write classifications describe supported operation contracts, not current execution readiness. Scene, rig, track and license checks remain NOT_EVALUATED; the Cascadeur application version is NOT_REPORTED. See capabilities and structured errors for the loaded-host contract, error fields and conservative handling of older hosts.

Doctor now reads the loaded host's contract and, when advertised as read-only, the current FBX entitlement. A matching contract does not establish rig safety or successful export. JSON remains the default; --format text explains each observed problem with a next step. See the diagnostic statuses.

Finger input uses local unit quaternions [w,x,y,z] and named finger segments, not those world-position targets. Read hand controls before editing. There is no universal fist preset or automatic motion generator. For connection failures, use troubleshooting.

For focused inspection, get_semantic_pose accepts roles, such as ["right_hand"], and include_joint_state: false. Omitted options keep the full 11-role result and read-only joint states. Discover support in the responding host's read_features; update and restart both processes before using these options. A matching write contract does not establish read-option support on an older host. See selective reads for examples and limits.

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; structured errors never authorize automatic retries.

  • rolled_back requires explicit verified restoration. recovery_required means stop writes and inspect or recover the preserved scene. Not every adapter proves rollback, and error text alone is not recovery evidence.

  • Character transaction journals are checked after native commit. Durable pose restoration preserves existing interpolation settings; it is still a single pose operation and can recompute adjacent interpolation.

  • 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. A local native acceptance check exercised capability discovery, preflight rejection, a verified rollback after an unachievable hand target, and a later semantic write/restore. See the recorded scope; this does not establish recovery for every adapter or connection on another machine.

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.

Available Tools

37 tools
export_fbxA
Destructive

Export the complete single-character scene with baked skeleton/mesh/animation via native FbxLoader. Full stored frame range only; ASCII, Y-up, Euler filter. Saves a NEW .casc copy first (scene identity changes). New FBX by default; replacing a file requires its exact expected_sha256. Rejects unsupported scopes. Read back files after timeout.

Inputs: options (required), scene_id (required), output_path (required), character_id (required), +2 more.

get_bridge_capabilitiesB
Read-only

Read contracts from the actual loaded host; runtime rig and license preconditions remain unevaluated.

Inputs: no named parameters.

get_character_poseA
Read-only

Read every character joint local/global transform plus all native Point targets in ONE call. Returned pose is writable by set_character_pose.

Inputs: frame (required), character_id (required).

get_character_skeletonA
Read-only

Read full native joint hierarchy, rig controls, bindings, constraint references and shared tracks by character UUID.

Inputs: character_id (required).

get_current_frameA
Read-only

Read current frame and available animation frame count.

Inputs: no named parameters.

get_fbx_export_statusA
Read-only

Read the current native FBX export entitlement and loader methods. No export or file writes. Method availability is not proof of a successful export.

Inputs: no named parameters.

get_global_transformB
Read-only

Read actual world position/quaternion at frame, default current.

Inputs: object (required), frame.

get_hand_poseB
Read-only

Read Cascy finger local rotations and verified hierarchy bindings; body hand Points do not control finger shape.

Inputs: frame (required), character_id (required).

get_local_transformB
Read-only

Read actual parent-relative position/quaternion at frame, default current.

Inputs: object (required), frame.

get_objectsB
Read-only

Read a bounded page of object names and types; names are not unique IDs.

Inputs: limit, offset.

get_poseA
Read-only

Read an explicit object list (Phase 2) OR all real Joints under root (Phase 3), with parents and local/global transforms. One round-trip; does not move playhead.

Inputs: frame (required), root, objects.

get_rig_semanticsB
Read-only

Discover and validate Cascy v1 role groups, native Point UUIDs, rig bindings and topology fingerprint. Driven joints are read-only. Refuses ambiguous names or unsupported topology.

Inputs: character_id (required).

get_scene_infoA
Read-only

Read current Cascadeur scene name, frame and object count.

Inputs: no named parameters.

get_semantic_poseA
Read-only

Read named Point targets in world scene units. Defaults to all 11 roles plus read-only joint states. Optional roles selects 1-11 unique semantic roles; include_joint_state=false omits joint states. Full rig validation always runs. A partial read does not validate animation quality or whole-body motion.

Inputs: frame (required), character_id (required), roles, include_joint_state.

get_semantic_pose_sequenceA
Read-only

Read 1-8 unique existing frames in ONE MCP call, in requested frame order. Optional roles and include_joint_state select values after complete rig validation. Uses native stored values, without moving the playhead or caching a rig between requests.

Inputs: frames (required), character_id (required), roles, include_joint_state.

get_transformB
Read-only

Read world position (scene units), rotation quaternion [w,x,y,z] and track key state for a unique object name.

Inputs: object (required), frame.

inspect_character_motionB
Read-only

Read native track curves, rigid-body mass-weighted COM and rig connection errors at every stored frame (max 121). Does not move the playhead.

Inputs: character_id (required).

list_charactersA
Read-only

List actual RigInfo owner UUIDs in the saved scene; names are display labels only.

Inputs: no named parameters.

offset_semantic_pose_sequenceA
Destructive

Translate every Point slot of each named role by its world-space [dx,dy,dz] at 1-8 existing frames. Each frame uses its own current targets. ONE checked transaction with full-scene snapshot and rollback verification. Creates full-character keys and LINEAR intervals; does not preserve authored easing. Returns actual solved edited roles, not requested values. Not idempotent: another call adds the offset again. Never auto-retry after timeout; read back first. No rotation, scale, timeline extension or finger curling.

Inputs: frames (required), offsets (required), scene_id (required), character_id (required).

offset_semantic_pose_sequence_preserving_curvesA
Destructive

Offset named Point role groups at 1-8 EXISTING KEYS on their tracks, in one checked transaction. Preserves key layout, track membership, interpolation, easing weights and supported tangent metadata; no key creation. Writes only selected Point channels. Checks all-frame geometry, unedited FIXED/baked tracks and Point keys outside requested frames. Rejects editing FIXED tracks, custom tangents, additive stacks, cycles or unavailable state. Edited trajectories and solver-coupled rig Points/Joints can change; read actual adjustments. Not idempotent; read back after timeout. No rotation, finger curling or timeline extension.

Inputs: frames (required), offsets (required), scene_id (required), character_id (required).

ping_cascadeurA
Read-only

Confirm a live response from the Cascadeur host bridge.

Inputs: no named parameters.

play_animationA
Destructive

Start a bounded native Timeline.Play observation on a stopped scene. Returns pending: call stop_animation later for measured playback/stop evidence. Never advances frames with a script. Requires exclusive playback ownership; rejects edits while active.

Inputs: scene_id (required), end_frame (required), start_frame (required).

restore_pose_snapshotA
Destructive

Restore clip transforms from an opaque host-memory snapshot with identity/topology/key-layout guards and full readback. Not a general scene undo; refuses changed track structure. For character snapshots supply scene_id; uses bounded native Undo with full-state verification; refuses external scene edits. Durable variant: scene_id, character_id, path. Restores ONE pose across restarts; verifies joints before commit, recomputes adjacent interpolation, refuses incompatible rigs. Not a whole-clip backup.

Inputs: path, scene, scene_id, snapshot_id, +1 more.

retime_character_motionB
Destructive

Retime 2-8 complete synchronized character keys and set native interpolation/easing weights in ONE checked transaction. Preserves solved Point poses and verifies all joint key states; only exclusive IK character tracks. Snapshot/rollback automatic. No arbitrary tangent vectors or AI interpolation. Read back after timeout.

Inputs: keys (required), scene_id (required), character_id (required), stabilize_contacts.

save_pose_snapshotA
Destructive

Capture all local/global clip transforms and topology/key guards for a Joint subtree in host memory. Up to 32 snapshots per host session; invalid after restart. Alternatively supply scene_id and character_id for full real-character state and bounded native history (16 snapshots). Durable variant: scene_id, character_id, absolute new .json path and optional frame. Saves ONE pose, all Point controls and read-only joint verification; no vendor assets.

Inputs: path, root, frame, scene, +2 more.

save_scene_copyA
Destructive

Save the active native scene to a NEW absolute .casc file; never overwrite. Returns file SHA256. Native scene identity can change: rediscover afterwards.

Inputs: scene_id (required), destination (required).

set_character_poseA
Destructive

Write the complete native Point target set in ONE native transaction at an EXISTING frame (0-120). Rig solves joints; constraints and IK mode retained. Captures full-scene snapshot; failures automatically verify rollback. Exclusive C01 pose editing required; timeout is unknown outcome, read back before retry.

Inputs: pose (required), frame (required), scene_id (required), character_id (required).

set_current_frameB
Destructive

Switch to an existing frame; require expected scene name; returns actual frame.

Inputs: frame (required), scene (required).

set_global_transformB
Destructive

Set one joint in world space using the bounded batch engine; descendants follow through host update. Captures recovery snapshot first.

Inputs: root (required), frame (required), scene (required), object (required), +2 more.

set_hand_pose_sequenceA
Destructive

Write 1-8 frames of semantic left/right finger local unit quaternions in one checked native transaction. Only validated Cascy finger chains, not body joints. Preserves existing body keys and interpolation; read back after timeout.

Inputs: poses (required), scene_id (required), character_id (required).

set_keyframeA
Destructive

Create a key on an isolated unlocked object's track at an existing frame, preserving pose. Not per-channel keying. Timeout means unknown outcome; read back before retrying.

Inputs: frame (required), scene (required), object (required).

set_local_transformC
Destructive

Set one joint in local space using the bounded batch engine. Captures recovery snapshot first and interpolates linear FK tracks.

Inputs: root (required), frame (required), scene (required), object (required), +2 more.

set_poseA
Destructive

Batch-write 1-32 joints in one checked host transaction and one MCP call. Requires a <=121-frame, unit-scale, isolated-track linear FK Joint subtree. Automatically captures clip snapshot; returns before/after. Timeout is unknown outcome; read back before retry.

Inputs: root (required), frame (required), scene (required), pose_data (required), +1 more.

set_pose_sequenceA
Destructive

Write 1-8 unique existing frames of semantic Point targets in ONE MCP call / ONE checked native transaction. Patches merge with pre-transaction state. Failure checks restoration; unverified recovery locks further writes. No timeline extension. Read back after timeout.

Inputs: poses (required), scene_id (required), character_id (required).

set_semantic_poseA
Destructive

Patch named role/slot world-position targets in one native transaction; omitted slots retain the target frame values. Preserves rig constraints. Read solver-adjusted result; timeout means unknown outcome.

Inputs: pose (required), frame (required), scene_id (required), character_id (required).

set_transformA
Destructive

Set world position and/or unit quaternion [w,x,y,z] on an existing keyframe. Only isolated unlocked object tracks. Returns before/after. Timeout means unknown outcome: read back, never blindly retry.

Inputs: frame (required), scene (required), object (required), position, +1 more.

stop_animationA
Destructive

Stop only playback owned by this bridge; return actual frame observations and stop verification. Idempotent after automatic end stop. Cannot stop arbitrary external playback.

Inputs: scene_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 37 tools

    Disambiguation2/5

    Multiple tools overlap heavily in purpose: reading transforms via get_transform, get_local_transform, get_global_transform, get_pose, get_character_pose, and get_semantic_pose all retrieve similar data in different contexts, and writing transforms has many parallel variants. While descriptions distinguish contexts, an agent could easily misselect among this dense set.

    Naming Consistency5/5

    Tool names follow a consistent snake_case verb_noun pattern throughout (e.g., get_scene_info, set_pose, save_pose_snapshot, export_fbx). Minor variations in verb choice (e.g., inspect, retime) remain within a predictable convention.

    Tool Count2/5

    With 37 tools, the set is heavy and exceeds the typical 25+ threshold for 'too many.' While the domain is complex, many tools could be consolidated, and the large count increases cognitive load and selection difficulty.

    Completeness3/5

    The toolset covers reading/writing poses, transforms, sequences, snapshots, export, and playback, but notable gaps exist: no deletion of keyframes, objects, or characters; no creation of objects or characters; and no undo beyond snapshots. These omissions may force workarounds for lifecycle management.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects MCP-compatible clients to a live Blender scene for AI-assisted 3D workflows, enabling inspection and controlled operations on objects, materials, cameras, lights, render settings, animation, UVs, Geometry Nodes, imports, exports, and Python execution.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to control Cascadeur locally for scene and rig inspection, body and finger animation, keyframes, physics actions, camera control, PNG previews, and FBX import/export via stdio MCP.
      36
      10
      MIT