Cascadeur MCP

An independent local MCP server for controlling Cascadeur from Codex, Claude Desktop, Claude Code, Cursor, and other stdio MCP clients.

It provides 36 named tools for scene and rig inspection, body/finger posing, keyframes, interpolation, timeline selection, camera controls, PNG previews and FBX import/export. A curated action catalog exposes physics, AutoPosing, retargeting, cycles and review commands with explicit verification limits. An optional 37th tool enables advanced Python scripting.

Start with the AI operating guide. It explains which controls to use, how to verify body and finger animation, and which APIs to avoid. The guide is also served to agents as cascadeur://guide.

What was tested

The server was tested against a real Apple silicon Mac installation of Cascadeur reporting inHouse / Python API dev, with embedded Python 3.11. The supplied live test used the locally installed Cascy sample to animate the torso, arm and all 15 right-hand finger controls. It checked interpolated poses, rendered body/hand views, saved and reopened the .casc, and exported animation FBX. See the test report and capability limits.

This is a functional animation integration, not a guarantee of finished artistic quality. Cascadeur's API coverage is uneven. Physics/menu commands and advanced systems are labeled separately from operations verified in the live test. Windows and Linux are unverified; Claude and Cursor configuration is provided but their UIs were not tested directly.

Related MCP server: blender-ai-mcp

Install

Use Python 3.11 or newer in your normal operating-system environment:

git clone https://github.com/gprethesh/cascadeur-mcp.git
cd cascadeur-mcp
python3 -m venv .venv
.venv/bin/python -m pip install .

On Windows, use .venv\Scripts\python.exe in place of .venv/bin/python.

The server needs no API key. It uses your AI client's model and your installed/licensed Cascadeur application. It does not use Cascadeur's built-in MCP server, patch the app, or install Python packages into the app's embedded Python.

1. Generate your bridge and client settings

Choose absolute paths for the connection folder, animation workspace, and generated setup folder. Keep these folders local to your machine.

.venv/bin/python -m cascadeur_mcp \
  --bridge-dir "/absolute/path/cascadeur-session" \
  --workspace "/absolute/path/animation-projects" \
  --setup "/absolute/path/cascadeur-setup"

This writes:

• start_bridge.py: a script to run in Cascadeur.

• app/cascadeur_mcp/: a standalone copy of the app bridge.

• codex.toml, claude-desktop.json, and cursor.json: ready-to-merge client settings using the actual Python executable and paths.

Keep the generated app folder beside the startup script. Re-run setup after upgrading this server, then restart Cascadeur to load the new bridge code.

2. Start the bridge inside Cascadeur

Open Window → Python Console and execute this line, using the generated script's actual path:

exec(open("/absolute/path/cascadeur-setup/start_bridge.py").read())

Leave Cascadeur open. Start the bridge again after each app restart. The console can be closed after execution. A compatible Cascadeur build must supply csc, PySide6, the event-message manager and ModelEditor.fit_animation_size_by_layers.

Do not start Cascadeur's built-in MCP server for this integration.

Check the connection from a terminal:

.venv/bin/python -m cascadeur_mcp \
  --bridge-dir "/absolute/path/cascadeur-session" \
  --workspace "/absolute/path/animation-projects" \
  --doctor

3. Connect your AI client

Merge the generated settings into the client's existing configuration, preserving other servers. Use the same bridge directory and workspace in every client. Use literal absolute paths in JSON and TOML; do not leave ~, environment placeholders, or example paths.

Codex

Merge generated codex.toml into ~/.codex/config.toml, then restart the MCP connection in Codex settings. Example:

[mcp_servers.cascadeur]
command = "/absolute/path/cascadeur-mcp/.venv/bin/python"
args = ["-m", "cascadeur_mcp", "--bridge-dir", "/absolute/path/cascadeur-session", "--workspace", "/absolute/path/animation-projects"]
startup_timeout_sec = 30
tool_timeout_sec = 120

Official Codex MCP documentation.

Claude Desktop

Use Settings → Developer → Edit Config, and merge generated claude-desktop.json. On macOS the configuration file is ~/Library/Application Support/Claude/claude_desktop_config.json. Restart Claude Desktop.

{
  "mcpServers": {
    "cascadeur": {
      "command": "/absolute/path/cascadeur-mcp/.venv/bin/python",
      "args": ["-m", "cascadeur_mcp", "--bridge-dir", "/absolute/path/cascadeur-session", "--workspace", "/absolute/path/animation-projects"]
    }
  }
}

Official local MCP setup guide.

Claude Code

claude mcp add --transport stdio --scope user cascadeur -- \
  "/absolute/path/cascadeur-mcp/.venv/bin/python" -m cascadeur_mcp \
  --bridge-dir "/absolute/path/cascadeur-session" \
  --workspace "/absolute/path/animation-projects"

Use /mcp to inspect the connection. Long operations may need MCP_TOOL_TIMEOUT=120000 (milliseconds). Official Claude Code documentation.

Cursor

Merge generated cursor.json into ~/.cursor/mcp.json globally, or .cursor/mcp.json for a project. Reload Cursor and enable the cascadeur server. The generated entry includes "type": "stdio".

Official Cursor documentation.

Other clients

Launch the same Python executable and arguments as a local stdio MCP server. Image review requires support for MCP image content. A remote-only chat cannot launch an app on your computer without a local runtime.

4. First prompt

Read cascadeur://guide. Check Cascadeur's capabilities and inspect the active scene, rig, body controls, finger controls and tracks. Report the available operations and license restrictions before editing.

For an animation task, provide the character, reference, action, intended duration/FPS and output requirements. Have the agent checkpoint, block poses, inspect inbetweens, refine hands, and verify saves/exports.

Coverage

See tool schemas for machine-readable arguments, and the guide for workflows and restrictions.

Known limits

• Native Python video export crashed the tested Cascadeur build. It is not exposed as a normal tool. Capture PNG frames instead. See TESTING.md.

• Additive layers, mocap, AI motion generation, retargeting quality and rig generation are not claimed as verified features. Discover APIs and check your license before use.

• Menu actions report dispatch, not successful completion. Many commands are toggles, need a selection, or can open dialogs.

• The server checks normal input/output file paths against the workspace. This is not an operating-system sandbox. Projects may reference other assets.

• A timeout or application crash can leave an uncertain result. Inspect before retrying. Save checkpoints before substantial changes.

Advanced scripting

To expose cascadeur_run_script, add --allow-scripts both to the setup-generation command and to the server's client arguments. The generated settings include it when setup uses that flag.

Scripts execute with the user's full privileges inside Cascadeur, including file, process and network access. They bypass the workspace path checks used by normal tools. They are disabled by default. Read the scripting section of the AI guide before using them.

How the connection works

The AI client talks standard MCP over stdio to a Python process. That process writes requests into a local mailbox. A Qt timer in Cascadeur executes one request at a time on the app's main thread and writes a response. There is no HTTP listener, open network port, model dependency or remote relay.

The mailbox uses atomic writes, session identities, deadlines, cancellation cleanup, payload limits and a cross-process client lock. On Unix, the connection directory is owner-only. Windows uses the folder's inherited ACL; keep it in a private user directory. All clients share the active scene and selection, so avoid simultaneous artistic edits.

Development and testing

.venv/bin/python -m pip install '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/ruff check .

To reproduce the live test, start the bridge against a dedicated test workspace, then run:

.venv/bin/python examples/live_smoke.py \
  --sample "/Applications/Cascadeur.app/Contents/Resources/samples/Cascy.casc" \
  --workspace "/absolute/path/test-workspace" \
  --bridge-dir "/absolute/path/cascadeur-session"

The test creates/overwrites its named test scene and previews in that workspace. It uses the sample installed with Cascadeur; no vendor rig or app binaries are distributed by this repository.

License

This integration is MIT licensed. Cascadeur and bundled sample assets retain their own licenses. This project is independent of Nekki, OpenAI, Anthropic and Cursor.