Cartwheel MCP

Create and auto-rig characters. Generate, capture and edit their motion.

Cartwheel MCP connects your AI assistant to Cartwheel’s public API. Create a character from text or an image, upload and auto-rig your own model, then animate it. Generate body motion from text with swing-edit, constrain it with Motion Editor controls, or capture up to four performers from a video with Comic 4, including facial animation. Edit performances with paths and poses, loop or stitch clips, measure motion metadata, and run the bundled Three.js game reference.

Watch the Blender demo · Production setup walkthrough · MCP Blender workflow · More Blender examples

Three generated characters, one Blender scene

Lantern Port takes three text descriptions through character generation and auto-rigging, combines Comic 4 acting with swing-edit walking, then renders a miniature skyport with four camera shots and a frog close-up. The example includes the three rigged assets, exact prompts, reproducible Blender scripts, and the reviewed shoulder, face and Gaussian foot-contact fixes.

Watch Lantern Port · Rebuild the scene · Create and auto-rig characters

What you need

• Node.js 22 or newer and Git.
• A Cartwheel production account with API access and a project API key. Check the current plans; API access is not included in every plan.
• An MCP client that can launch local stdio servers. This repository runs on your machine; it is not a hosted MCP URL.
• Blender only if you want to render the examples. The MCP server itself does not require Blender.

1. Get a Cartwheel API key

1. Open Cartwheel, choose an API-enabled plan (Individual Pro or Team Pro or Team Scale), and create your account. Complete email verification and any plan setup shown by the site.
2. Open your Cartwheel dashboard and select API keys.
3. Create or reveal a key for your workspace/project. Key management may require a workspace administrator.
4. Copy the secret key value. The project ID and API Gateway key ID are not substitutes.

The setup guide includes a recording of the actual production signup interface and the steps that follow.

2. Install

git clone https://github.com/Cartwhl/cartwheel-mcp.git
cd cartwheel-mcp
npm ci

There is no compilation step. The source runs directly on Node.js.

3. Connect your assistant

For clients with a JSON mcpServers configuration, add the following. Replace the absolute path and provide your own key through the client’s environment or secret settings:

{
  "mcpServers": {
    "cartwheel": {
      "command": "node",
      "args": ["/absolute/path/to/cartwheel-mcp/src/index.mjs"],
      "env": {
        "CARTWHEEL_API_KEY": "YOUR_CARTWHEEL_PROJECT_API_KEY"
      }
    }
  }
}

Use an absolute path: clients may launch the process from a different working directory. Restart or reconnect the client after changing its configuration.

For Codex, add this to ~/.codex/config.toml and make CARTWHEEL_API_KEY available in the environment that launches Codex:

[mcp_servers.cartwheel]
command = "node"
args = ["/absolute/path/to/cartwheel-mcp/src/index.mjs"]
env_vars = ["CARTWHEEL_API_KEY"]

See the Codex MCP configuration documentation for app setup and environment settings.

For a local terminal session, you can instead copy .env.example to .env, enter your key there, and run npm start. The .env file is gitignored. A running stdio server waits quietly for MCP input; it does not display a web page.

4. Choose a motion workflow

For swing-edit, ask:

Use the swing-edit workflow. Find an accessible seed motion, create an isolated scene on MHR, and generate a new relaxed walk from text only. Review the completed performance, apply it, then export the scene with root travel intact.

swing-edit uses an existing scene timeline slot as its skeleton and export template. Text-only requests omit both constraints and keyPoses; the old body performance does not condition generation. Source-dependent hierarchy and unmapped finger channels still need attention. The swing-edit guide covers character selection, static hand poses and the complete lifecycle. Use edit_motion for swing-edit; generate_motion.requestedModel belongs to the separate standalone generation API.

For a standalone Swing batch, try:

List my Cartwheel characters. Use one to generate an eight-second joyful disco dance with Swing. Submit it once, check the batch until it finishes, and give me the BVH download link.

The workflow is:

list_characters → generate_motion → get_batch → list_batch_motions → download BVH

Generation is asynchronous and consumes Cartwheel credits. Submitting another generation does not check the first one; it starts another job. Poll the returned batch instead.

Example generate_motion arguments:

{
  "batchName": "My first MCP animation",
  "prompts": ["A person dancing a playful disco groove in place"],
  "requestedModel": "swing",
  "swingProperties": { "duration": 8 },
  "exportSettings": {
    "characterID": "REPLACE_WITH_AN_ID_FROM_LIST_CHARACTERS",
    "exportType": "bvh",
    "forward": "Z",
    "up": "Y",
    "frameRate": 24,
    "frameStepSize": 1
  }
}

For list_batch_motions, pass both batchID and limit (for example, 10). Responses retain the API’s pagination tokens and download URLs. Asset URLs can expire; retrieve the motion again for a fresh link.

Tools

List pagination uses nextToken. Search requires pageSize and uses the response’s lastSort array as searchAfter.

Character creation and auto-rigging

Use create_rigged_character or cartwheel://workflows/characters. Ask your assistant:

Create a friendly forest courier from this reference image, wait for the rigged character, and test a short swing-edit walk in Blender.

Or:

Upload this GLB, auto-rig it, download the rigged GLB and config, and inspect the shoulders and knees with a short animation.

Text/image: generate_character_batch → get_batch → list_batch_characters → get_character
Model:     create_character_upload → upload bytes → submit_character_upload → get_character

The older prepare_character_generation → submit_character_generation tools remain available for existing prepared jobs and clients that require the single-character flow. Use the batch flow for new work.

For a reference image, first use create_media_upload and upload the PNG, JPG, JPEG or WebP bytes. Each batch job accepts exactly one prompt or mediaID; mixed batches are supported. INSPIRATION generates a new image from a reference, while DIRECT uses it unchanged. Batch submission returns a batchID and idempotencyKey; poll the batch rather than submitting another request. A model upload needs no config to start: the API auto-rigs unrigged meshes and detects existing rigs. The client handles file bytes with the bundled upload helper.

List every character in the batch, then wait for uploadStatus: "COMPLETE" and actual deliverables on each one. For uploaded models, use baseFbxURL or baseGlbURL for the rigged result; characterFileURL may still be the original unrigged mesh. Generation’s 3D_CONVERT_COMPLETE is not rig completion. Failed or validation-required jobs need inspection, not automatic resubmission.

The complete character workflow covers optional configs, processing states, timeout recovery, downloads and reuse with swing-edit. Review the resulting rig with a short animation before building a full scene. Auto-rigging does not promise facial blendshapes or conversion to MHR.

swing-edit game animation and Motion Editor

Version 0.7.0 includes the swing-edit Motion Playground: one MHR character, four swing-edit body performances, idle/walk/run transitions, an interruptible right-arm signal, contact-driven effects and a small crowd. Static hand poses are chosen explicitly. The native MHR pose corrections handle deformation; there is no consumer shoulder-rotation patch.

npm run example:game

Open the printed localhost URL. The bundled game needs no API key. Walk/run cadence follows actual movement distance through reviewed interior cycles. Hip sway is retained; the signal replaces the corresponding right-arm locomotion tracks. Source & metrics shows each swing-edit prompt and the playback measurements. Each clip’s metadata also records its seed, skeleton identity and source/prepared hashes. The preparation helper handles setup frames, trims, event remapping and measured travel.

Two MCP workflows work together:

• swing_edit_motion / cartwheel://workflows/swing-edit: generate, constrain, review, apply and export.
• game_ready_animation / cartwheel://workflows/game: prepare compatible assets and integrate them into the playable controller.

find an accessible seed motion → create_scene → get_scene
  → set_scene_character → edit_motion / edit_key_poses
  → get_motion_edit → review → apply_motion_edit
  → export_scene → get_scene_exports
  → client prepares BVH + metadata → Three.js game

The swing-edit workflow documents every supported Motion Editor primitive:

Read the coordinate contracts before constructing constraints: inline positions are meters, native pose positions retain source units, and rotations are axis-angle radians. End-effector constraints do not remap arbitrary MHR or Axel pose arrays. The bundled SOMA-30 joint order identifies the expected order; it is not a rig converter. Ordinary inline constraints and native key poses cannot be mixed; the documented built-in repath envelope is the supported exception.

Edits are asynchronous and consume credits. Submit once and poll the existing job. Loop/stitch operations act on motion IDs, not editor job IDs or unapplied scene edits; they create new motion IDs and can take up to four minutes. After an uncertain mutation, inspect existing state before resubmitting.

Contacts are kinematic estimates. Authored signal/VFX timing is separate. Selected cycles, transitions, masks and character retargets still need visual review; switching to swing-edit is not a general repair for every motion/character combination. The audit records the changes and limits.

See the game workflow, runnable example and asset provenance. Reconnect the MCP after updating to discover 32 tools and five workflows.

Comic 4: video to editable 3D

Watch the 10-second camera reveal · Clean Blender shot · How the demo was made

The demo captures two performers together, preserves their timing and placement, and turns them into botanical androids in a conservatory. A moving Blender camera shows a viewpoint absent from the reference. The scene, costumes and camera work are authored; Comic 4 supplies the body, hand and facial performances.

Ask your assistant:

Use the Comic 4 Blender workflow to capture both people and their faces from this video. Keep their relative placement, import the complete performance into Blender, and render a camera angle that wasn’t in the original video.

The comic4_blender_scene prompt and cartwheel://workflows/comic4 resource provide the full process:

create_media_upload → client PUTs video bytes → generate_motion_from_video
  → get_batch → list_batch_motions → import every actor into Blender

Use an authorized video of at most 30 seconds and less than 250 MB. Select comicModel: "comic4", set numPeople explicitly for a group, and enable facialCapture when needed. The runnable upload helper and complete request example explain each step. The helper runs through your client’s local execution tools; the MCP server has no filesystem access tool.

Capture returns editable performance data, not a finished scene. Preserve actor indices and shared world placement. Retrieve all body and face outputs from list_batch_motions, including the source-camera FBX when available. The API’s legacy faceURLs[i].bvhURL field points to an MHR FBX, not a BVH; a custom character needs a compatible rig or facial retargeting. Use get_motion with characterID and bodyIndex to retarget a particular actor’s body. See the Comic 4 workflow for import checks and camera-reveal guidance.

After updating, reconnect your MCP server to discover the new tools, prompt, and resource.

Default Blender workflow in MCP

The server exposes the approved grounding and rendering process directly through MCP:

• Prompt: grounded_blender_scene, with an optional scene description.
• Resource: cartwheel://workflows/blender.
• Bundled files: Blender scripts, validation, and all four generated example motions under examples/blender/.

Choose the prompt in a client that supports MCP prompts, or ask your assistant:

Use Cartwheel’s grounded Blender workflow to make a playful robot scene. Start with a motion preview, check foot contact and pose continuity, then render the final movie.

The server instructions direct Blender requests to this workflow. The complete guide covers generation, preserved root travel, Gaussian contact easing, stable knee IK, continuous foot yaw, validation, and final rendering. The example driver runs the contact and continuity checks before rendering movies. Your MCP client’s authorized local tools run Blender and handle files.

After updating this repository, restart or reconnect the MCP server so your client discovers the new prompt and resource.

Blender gallery

The examples use Cartwheel-generated BVH motion, procedural characters and sets, and Blender Cycles rendering. The scene source and original music are included.

See the Blender guide for source files, rendering instructions, and motion provenance.

Paths and poses: generate_motion is text generation. Use the new edit_motion and edit_key_poses tools for Motion Editor conditioning. The older Moon Mail demo uses a Blender trajectory and contact solve; it was not generated with these editor tools.

Security and scope

• Calls go to Cartwheel’s fixed public production API using your own project key.
• The server exposes 32 explicit tools. It has no generic HTTP proxy, database access, shell tools, account administration, billing, or deletion tools.
• analyze_motion reads bounded BVH assets only from approved Cartwheel production storage. API keys are never sent to asset storage. The optional game server is a separate loopback-only process without an API proxy.
• It does not expose callback registration, subscriber management, or impersonation fields.
• Requests are validated, redirects are rejected, and failed requests are never automatically retried.
• Keys stay in the local environment. They are not bundled in the package or examples.
• Tool results are visible to your MCP client and its model provider. Treat returned metadata as data, not instructions.

Read SECURITY.md for the trust boundary and reporting details.

Troubleshooting

Development

npm ci
npm test
npm pack --dry-run

Tests use the official MCP client, in-memory transports, and a real stdio subprocess. They validate tool and workflow discovery, prompt/resource retrieval, request schemas, authentication, pagination, character generation, model/image upload, auto-rig submission and status handling, motion generation submission, error redaction, route boundaries, and package contents without using real credentials or spending credits.

src/tools.json, src/game-tools.mjs, src/swing-edit-constraints.mjs, src/scene-tools.mjs and src/character-tools.mjs contain the selected authenticated API contracts. Keep changes aligned with the public Cartwheel API documentation. The server is self-contained and does not require any other Cartwheel repository. Three.js supplies BVH loading, transforms and animation utilities; there is no local model runtime.

Distribution

This GitHub repository is the source distribution and installation entry point. It is not itself a hosted MCP service. The npm manifest is ready for packaging, but this README does not claim an npm release or MCP Registry listing.

The MCP Registry is a separate discovery service that points to installable packages or remote servers. Registry listing and package publication are separate from publishing source on GitHub.

License

MIT. Cartwheel service access and generated assets remain subject to your Cartwheel account terms.