MCP for Cascadeur

Inspect rigs, edit controller animation and review the result through MCP. There are 49 structured tools, plus optional Python execution for the rest of Cascadeur's API. Control groups are user-defined and work with inspected native rigs rather than one hard-coded character layout.

The stdio process uses the official MCP Python SDK. Native operations run through the script runner shipped with Cascadeur, on its main thread. Setup copies this project's host modules to a persistent user directory; cleaning the uv cache does not remove the host bridge. It installs no Python dependencies or replacement Qt libraries inside Cascadeur.

Setup

Install uv and Cascadeur first. This release requires a build containing Scripts > MCP > Start script server. Native development and acceptance use Windows Cascadeur 2026.2.3. Other operating systems have Python contract checks, not native acceptance.

From PowerShell or another terminal:

uvx --from git+https://github.com/Rickcy/mcp-for-cascadeur mcp-for-cascadeur setup --install-startup

This discovers Cascadeur, installs a startup hook, and adds an MCP entry to Codex. Existing client settings are preserved and backed up. No clone or manual virtual environment is required. Git installs are recorded in the client configuration with their exact commit hash. The package is not published to PyPI yet.

Restart Cascadeur, open or create a scene, then reconnect the MCP server in Codex. The welcome screen alone does not emit the scene-idle events needed to execute scripts. A normal terminal check is:

uvx --from git+https://github.com/Rickcy/mcp-for-cascadeur mcp-for-cascadeur doctor

Useful setup options:

# Enable the full Python API tool as well as structured tools.
uvx --from git+https://github.com/Rickcy/mcp-for-cascadeur mcp-for-cascadeur setup --install-startup --allow-python

# Choose the application and the directory allowed for scene, image and JSON files.
uvx --from git+https://github.com/Rickcy/mcp-for-cascadeur mcp-for-cascadeur setup --cascadeur-home "C:\Path\Cascadeur" --workspace "D:\Animation" --install-startup

Without --install-startup, setup generates start_bridge.py and prints its location. Execute that file in Cascadeur's Python console after opening a scene. Use --client none when managing client settings yourself. For Claude Desktop, Cursor or another stdio client, add:

{
  "mcpServers": {
    "cascadeur": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Rickcy/mcp-for-cascadeur", "mcp-for-cascadeur"]
    }
  }
}

Use an absolute path to uvx if your desktop client cannot find it. Settings and the stable host runtime live in the user's application-data directory under mcp-for-cascadeur. MCP_FOR_CASCADEUR_HOME overrides this location.

For a downloaded wheel, keep the external tool installed and use its registered executable instead of a temporary package source:

uv tool install "C:\Downloads\mcp_for_cascadeur-0.1.0-py3-none-any.whl"
uvx mcp-for-cascadeur setup --install-startup --local-tool

Related MCP server: Cascadeur MCP

Animation workflow

1. Read app_status, app_capabilities, objects_list and tracks_list.

2. Use object_inspect to find actual body, hand and finger channels. IDs avoid ambiguous names. Bind convenient names using rig_profile_create.

3. Save a native scene copy. pose_snapshot captures a selected pose, while scene_save preserves a whole clip.

4. Read poses, build keyframes, and preview a plan with motion_sample or motion_mirror. Plans contain ordinary JSON and do not edit the scene.

5. Apply pose_apply_sequence. Timeline extension is explicit. Readback reports target error and solver adjustments; a successful write can still alter other controls. position_tolerance and rotation_tolerance explicitly set readback acceptance (scene units and radians); they do not change the native solver.

6. Sample inbetweens, capture body and hand views, and reopen a saved .casc. Check contacts, silhouettes and exported animation in the receiving app.

Tool groups:

The server also exposes cascadeur://guide and cascadeur://tools resources. Run mcp-for-cascadeur tools --json from an installed tool environment to inspect all parameter contracts.

Scope

This is an initial development release. It does not guarantee finished animation from a prompt. Physics, AutoPosing and retargeting menu actions report dispatch; the affected native tool, selection and license still determine the result. General Python execution has the same privileges as Cascadeur and is optional.

Structured retiming currently supports standalone, unparented Basic/Transform objects. It rejects constrained rig tracks rather than treating derived global channels as independent authored channels. Use inspected native actions or Python for rig-specific retiming. Pose writes support native Transform channels, including controller and finger channels; solvers may adjust requested targets.

Pose snapshots do not preserve curve metadata or an entire clip. Native Undo is not advertised as a verified rollback mechanism. After a timeout or lost native connection, the write outcome is unknown: read back before retrying a relative edit or action. Keep the vendor HTTP runner bound to loopback.

Updating and removal

Repeat setup with uvx --refresh --from <source> ... setup, then restart both Cascadeur and the MCP client. Files on disk do not reload modules already imported into the native process. Modified or unrelated startup hooks are preserved.

mcp-for-cascadeur uninstall removes this project's recorded startup hook and Codex entry. It keeps scenes, workspace files and settings. A permanent tool installation, if used, can then be removed with uv tool uninstall mcp-for-cascadeur.

Development

uv sync --extra dev
uv run mcp-for-cascadeur --help
uv run ruff check src tests examples
uv build

See CONTRIBUTING.md, native API notes and validation results for test scope and native evidence.

Code is MIT licensed. Cascadeur and its installed assets retain their own licenses.