⚡ Motion MCP

Motion MCP plugs into Codex, Claude Code, Cursor, or any MCP-compatible agent and turns an existing codebase into a living, animated product. It scans your app, understands your screens and flows, writes Rive-like state-machine experience specs, compiles them through an open scene format (SceneDoc), generates framework-native animation code for React, React Native, Flutter, Unity, Three.js, and React Three Fiber (R3F), and stages everything as reviewable diffs that apply only after approval. Supports both 2D UI/character vector motion and text-to-3D skeletal animation powered by diffusion.

No rewrites. No invented runtime. No generated app replacing the real one. The motion lands inside your components, bound to your app state, rendered by your stack.

Motion MCP expanded from 2D vector animations into full text-to-3D skeletal animation diffusion, integrating the capabilities of kimodo.cpp. 52 → 64 MCP tools, 213 → 230+ tests, 29 → 32 packages:

Motion MCP closed the loop that separates it from every generate-and-hope tool in this space. 38 → 52 MCP tools, 154 → 213 tests, 27 → 29 packages:

Schema evolved without breaking anyone: temperament, binding converters (Rive-view-model-style), per-bone weights, and 3D properties (origin3d, restRotation, is3d, camera) are additive SceneDoc v1 extensions under a documented versioning contract (docs/scenedoc-v1-extensions.md).

Docs: Getting started · Tool reference (64 tools) · SceneDoc spec · HF Spaces deploy

Rive treats AI as an operator of a human-centric editor. Motion MCP deletes the editor: the repo is the file browser, the chat is the canvas, the diff is the review UI.

Two other tools define this space. Anim8 (tryanim8.com) is a manual, browser-based keyframe editor — Figma Motion import in, MP4/animated-SVG out. No AI generation, no state machines, no MCP. Rive's MCP ecosystem (official Rive MCP, plus the third-party 139-tool RiveMCP) makes an agent a tool executor over Rive's editor: it builds whatever you specify — scenes, state machines, data binding — but RiveMCP states plainly that it "won't draw original illustrations… an animation engineer, not an illustrator."

Motion MCP's wedge is the pieces neither ships:

Honest scope notes for evaluators: video tracing produces layered-flipbook SceneDocs (contour-traced keyframes with temporal reduction), and since the video-to-rig milestone it also tracks parts across those keyframes (IoU + centroid matching) to attach an inferred SceneDoc rig — returned as a reviewable rigProposal on vectorize_video, with degenerate tracking staying pure flipbook and saying why. This is deterministic contour tracking, not neural pose estimation: occlusion and same-color merges can still confuse part identity. Asset generation produces structured vector SVG — not raster diffusion illustration. And unlike RiveMCP's 267 runtime types, we don't target .riv output at all: SceneDoc compiles to native host-framework code, while import_riv reads .riv in.

Anim8 is where you animate by hand. Rive MCP builds what you specify. Motion MCP plans, generates, verifies, and ships.

flowchart LR
    subgraph AGENT["🤖 Coding Agent (Codex / Claude / Cursor)"]
        T["MCP Tools<br/>64 tools"]
    end

    subgraph RESEARCH["🔍 Understand"]
        S["scan_codebase<br/>scan_assets"] --> R1["auto_research_motion"]
        R1 --> R2["research_app_motion<br/>flows · screens · signals"]
        R2 --> R3["research_state_machine_experience<br/>layers · states · transitions<br/>listeners · ViewModel bindings"]
    end

    subgraph ASSETS["🎨 Assets & 3D Diffusion"]
        A1["2D Vector Lanes<br/>Simple / Premium QuiverAI"]
        A2["3D Motion Diffusion<br/>kimodo-bridge (SMPL-X22)"]
        A3["Retargeter<br/>Mixamo · Unity · Unreal · BVH"]
        A2 --> A3
    end

    subgraph SCENE["📐 Scene Graph"]
        SG["SceneDoc v1 (2D + 3D)<br/>deterministic motion grammar<br/>quaternion + euler tracks"]
        V["validateSceneDoc<br/>reference sampler"]
        SG --> V
    end

    subgraph EMIT["⚙️ Emit & Integrate"]
        E1["React / Next<br/>Framer Motion · GSAP"]
        E2["React Native / Expo<br/>Reanimated 3 · react-svg"]
        E3["Three.js / R3F<br/>useGLTF · useAnimations"]
        E4["Unity<br/>Mecanim 3D .anim YAML · UI"]
        E5["Flutter β<br/>AnimationController"]
        P["ast-patcher<br/>TS AST import patching"]
        EX["exporters<br/>BVH · Lottie · animated SVG"]
    end

    subgraph SHIP["✅ Ship"]
        D["Staged diffs<br/>.motion-mcp/diffs"]
        PV["preview_animation<br/>preview_3d_motion"]
        AP["apply_motion_diff<br/>+ project validation"]
    end

    T --> S
    R3 -->|"state-machine-experience.json"| SG
    A1 --> SG
    A3 -->|"3D clips · rigs"| SG
    SG --> E1 & E2 & E3 & E4 & E5
    P --> D
    E1 & E2 & E3 & E4 & E5 --> D
    SG -.-> EX
    D --> PV --> AP

generate_animation and generate_3d_motion compile intent into SceneDoc artboards (both 2D and 3D), and emitters render native framework code — React Framer Motion, React Native Reanimated, Flutter, Three.js / React Three Fiber, and Unity Mecanim .anim curves.

SceneDoc is motion-mcp's unified interchange format. It merges the two worlds that normally live apart in motion tools: interactive UI state machines (Rive-like) and keyframed character clips (baked skeletal data).

{
  "formatVersion": 1,
  "sceneId": "scene_landing",
  "artboards": [{
    "artboardId": "page_cta",
    "sourceFile": "app/page.tsx",
    "layers": [
      { "layerId": "layer_main", "targetParts": ["cta-glow", "cta-label"], "initialStateId": "state_idle" }
    ],
    "clips": {
      "clip-state_success": {                       // compiled by the motion grammar
        "durationMs": 620,
        "tracks": [
          { "targetPart": "*", "property": "scale",
            "keys": [{ "t": 0, "value": 1 }, { "t": 240, "value": 1.08, "easing": "easeOut" }, { "t": 620, "value": 1 }] },
          { "targetPart": "*", "property": "rotate",
            "keys": [{ "t": 0, "value": 0 }, { "t": 240, "value": 1.5 }, { "t": 620, "value": 0 }] }
        ]
      }
    },
    "stateMachines": [{
      "initialStateId": "state_idle",
      "states": [{ "stateId": "state_hover", "name": "Hover", "kind": "single", "clipId": "clip-state_hover" }],
      "transitions": [{ "fromStateId": "state_idle", "toStateId": "state_hover", "event": "pointerEnter",
                        "durationMs": 180, "interpolation": "spring" }]
    }],
    "bindings": [{ "property": "isLoading", "targetPart": "cta-label", "source": "app-state" }],
    "semantics": { "reducedMotionSafe": true }
  }]
}

Semantic states compile deterministically into keyframed clips — same input, same output, every time:

Per-part staggering is baked into keyframe times, so multi-part assets choreograph themselves. A reference sampler (sampleSceneTrack) evaluates any track deterministically — it is the ground truth the conformance suite pins against.

graph TD
    subgraph SERVER["MCP Server (@motion-mcp/server)"]
        MCP["64 MCP tools · stdio + HTTP bridge"]
    end

    subgraph UNDERSTAND["Understanding"]
        CS["codebase-scanner"]
        AR["app-researcher"]
        AU["auto-researcher"]
        SMR["state-machine-researcher"]
        MP["motion-planner"]
    end

    subgraph CORE["Core Engines"]
        SP["svg-parser<br/>@xmldom/xmldom"]
        SGR["scene-graph<br/>SceneDoc v1 (2D + 3D)"]
        AE["anatomy-engine<br/>species rigs"]
        KB["kimodo-bridge<br/>Kimodo.cpp + Mock"]
        RT["retargeter<br/>SMPL-X · Mixamo · BVH"]
        MR["motion-runtime<br/>zero-dep clip player"]
    end

    subgraph EMITTERS["Emitters"]
        ER["emitter-react"]
        ERN["emitter-react-native"]
        ETH["emitter-threejs<br/>R3F · Three.js"]
        EF["emitter-flutter β"]
        EU["emitter-unity β<br/>3D .anim YAML + UI"]
    end

    subgraph SUPPORT["Support"]
        QP["quiver-provider<br/>rotation · retries · pricing"]
        CL["credits-ledger<br/>reserve→commit→refund"]
        AP2["ast-patcher<br/>TypeScript API"]
        VA["validator"]
        ST["shared-types"]
    end

    MCP --> UNDERSTAND & CORE & SUPPORT
    CS --> AR --> SMR --> SGR
    AU --> SMR
    MP --> SGR
    SP -->|"pathTree · rig reports"| AE & SGR
    KB --> RT --> SGR
    SGR --> EMITTERS
    MR -->|"MotionDoc ⇄ SceneClip"| SGR
    AP2 -->|"patchIntoSource"| SERVER
    ST -.->|"types everywhere"| SERVER & UNDERSTAND & CORE & EMITTERS & SUPPORT

Every generated component ships with: reduced-motion handling, semantic labels, controlled/uncontrolled state support, and a host-side state machine you own — nothing phones home at runtime.

Understand the codebase

3D Skeletal Motion & Diffusion (Kimodo.cpp / Pluggable)

Research & plan

Generate assets

Animate & ship

Every generated/ingested SVG carries a rig report: which roles (eyes, head/body, mouth/beak, limb/wing, tail, shadow, sparkle) were detected, what they can bind to (eye-follow, blink, press-depress…), and what's missing — verify state-machine readiness before generating code.

Characterize anything with rig_asset: the auto-rigger turns any indexed SVG (or raw source) into a SceneDoc v1 rig block — bones from detected anatomy, an eye look-at IK chain, and ambient secondary motion (breathe 3400 ms, blink 4200 ms, tail spring, wing sway). Species schemas cover human-biped, avian-crow, generic-quadruped, insect, vehicle (chassis/cab/headlights/wheels), and a universal blob fallback — so every file, even one with no recognizable anatomy, ships alive by default.

Bring the whole app to life with animate_app_life: one call gives every indexed SVG asset an ambient state machine (idle breathe → hover lift → press squash, plus blink/wobble/reward-pop when anatomy supports it), auto-rigging characters along the way — staged as a single reviewable diff. Then bind_motion_to_state wires generated components to real app state: bound properties become a typed data prop that drives machine inputs (hasError → error shake, isLoading → active emphasis, isSuccess → reward pop).

Close the loop with review_animation: every generated scene can be self-verified before it ships — structural checks catch unsorted keys, out-of-range values, loop-seam pops, and micro-jitter; headless render checks catch static output (tracks targeting missing part ids) and blank frames. Reports score 0-100, persist under .motion-mcp/critiques/, and return deterministic fixes the host agent can apply. Works immediately after ingestion via the ambient-scene fallback — no research step required.

The critic's scoring contract lives in an editable rubric file, not hardcoded constants. Ship defaults replicate historical behavior; a project overrides anything via .motion-mcp/rubric.json (deep-merged over defaults):

{
  "version": 1,
  "scoring": { "failPenalty": 25, "warnPenalty": 8, "passThreshold": 100 },
  "checks": { "easing-mechanical": { "severity": "fail" }, "micro-jitter": { "enabled": false } },
  "curveLint": { "linearEasingMinSpanMs": 120, "velocityJumpRatio": 6 },
  "judge":   { "provider": "mock", "alivenessThreshold": 55 },
  "repair":  { "maxAttempts": 3, "allowedFixes": ["sort-keys", "clamp-bounds", "loop-wrap", "rewrite-linear-easing"] }
}

New verification tools on top of review_animation:

Run the loop standalone from the CLI:

pnpm critic examples/verify-loop/broken-scene.json          # exits non-zero if unrepairable

apply_temperament resolves a named preset (calm, energetic, nervous, playful, precise, heavy) or explicit energy / weight / warmth / precision axes in [0,1] into a deterministic motion profile — duration scaling, easing substitution, overshoot/squash/stretch budgets, secondary-motion amplitude — and rewrites any component's compiled scene to match. Timing and easing only; amplitudes are never invented. Staged output lands in .motion-mcp/scenes/ for review before use.

export_asset bakes a compiled state to animated SVG, Lottie JSON, GIF, MP4, or WebM — choosing automatically from the stated destination (web → animated-svg, flutter/ios/android → lottie→gif fallback, unity/video → gif/webm/mp4) with a recorded fallback trail when a format can't render. render_preview produces a base64 GIF of any state with no staged diff required.

Schema extensions (temperament block, binding converters à la Rive view models, per-bone weights) are additive under SceneDoc v1 — see docs/scenedoc-v1-extensions.md for the versioning contract.

The master pipeline is now wired as one tool:

any asset ──▶ ensoul_asset ──▶ [perceive] ──▶ [generate] ──▶ [verify] ──▶ [repair] ──▶ [preview]
   svg ──────────────▶ named parts + anatomy
   png ──────────────▶ paint-region parts + rig proposal
   gltf ─────────────▶ joint hierarchy / inferred band chain
                                        │
        prompt + temperament drive easing, overshoot,
        squash-stretch, stagger, durations
                                        │
                    self-check gates nextTool routing:
        ok → review_animation   ·   broken → auto_repair

Each stage also stands alone as its own tool, so agents can compose or override any step — ensoul_asset is the default happy path, not a black box.

pnpm test          # node --test — 213 tests across 42 suites
pnpm typecheck     # strict TS across all 29 packages
pnpm build         # topological build

Highlights:

• Conformance harness — one canonical SceneDoc fixture drives all four emitters. Asserts every scene state appears in each target's output, transition edges survive compilation, and legacy mode stays byte-stable.
• Golden frames without a browser — pinned numeric samples from the reference evaluator (e.g. success-pop scale at t=120ms ⇒ 1.06 ± 1e-9) define the timing truth every future renderer must honor.
• Byte-deterministic generation — identical inputs produce identical files modulo timestamps.
• Real parser tests — multi-line attributes, comments, entities, transform composition, CSS specificity, <use> cycles, malformed-input resilience.

Two lanes, one pipeline:

• Simple lane — the host coding model generates SVG from a strict brief + acceptance checklist; ingest_svg_asset validates and indexes it. Zero marginal cost.
• Premium lane — QuiverAI structured SVG when complexity or brand importance justifies credits. Keys stay server-side.

Resilience built in:

• QUIVERAI_API_KEYS round-robins comma-separated keys, rotating away on 401/402/429
• Exponential-backoff retries on 429/5xx, honoring x-ratelimit-reset
• Fallback pricing matches live Quiver rates (arrow-1.1 = 20 cr, arrow-1.1-max = 25 cr)
• Batch mode isolates failures — one bad item never aborts 64
• Credits reserve ceil(quiver_price × 2), commit only after a usable SVG stages

Production billing defaults: Free 100 cr/mo · Pro $20/mo 2,000 cr · Team $50/seat 5,000 cr · Topup $10/1,000 cr.

Beyond UI motion, the same engines drive a full exercise system:

• anatomy-engine — species schemas turn plain SVGs into rigged characters: a crow "waves" with wing lift + head bob; a human waves with arms
• motion-runtime — zero-dep humanoid skeleton player: squat/jumping-jack/curl/lunge clips, base+overlay crossfading, hysteresis rep counting
• apps/exercise-demo — web studio: procedural character, cheer/form overlays, optional BlazePose camera rep counting, SVG mascots reacting to the same event stream
• apps/exercise-mobile — Expo shell running the identical runtime via pure-TS FK projected into react-native-svg
• pipeline/ — Python offline baking: MotionDoc interchange, RDP reduction + quantization, retarget solver, ARDY adapter. Baked JSON plays directly via sceneClipFromMotionDoc

pnpm --filter @motion-mcp/exercise-demo dev   # http://localhost:5175

pnpm install
pnpm build
pnpm dev:mcp          # stdio MCP server

Wire it into your agent — e.g. Claude Code:

claude mcp add motion-mcp -- node /absolute/path/to/motion-mcp/packages/mcp-server/dist/index.js

Or add to .mcp.json (this repo ships one — it doubles as a local Codex plugin via .codex-plugin/plugin.json):

{ "mcpServers": { "motion-mcp": { "command": "node", "args": ["packages/mcp-server/dist/index.js"] } } }

Local dev notes: credits ledger lives in .motion-mcp/credits.json with a default grant; Quiver runs in deterministic mock mode unless keys are set (MOTION_MCP_QUIVER_MOCK=1 forces mock).

scan_codebase({ rootPath: "." })
scan_assets({ rootPath: "." })
feed_concept({ brandConcept: "…", brandPersonality: ["precise","alive","playful"], logoSvgPath: "public/logo.svg" })
auto_research_motion({ brief: "highest-leverage motion improvements" })
research_state_machine_experience({ brief: "Rive-like page specs first" })

estimate_asset_lane({ screenId, assetBrief: "premium animated logo mark" })
generate_premium_svg_asset({ assetBrief: "…", placement: { screenId, moment: "first brand impression" } })

generate_animation({
  componentId,
  options: { intensity: "expressive", patchIntoSource: true, usageAnchor: "<Button>Buy</Button>" }
})
preview_animation({ diffId })     // inspect the staged diff
apply_motion_diff({ diffId })     // writes files + runs project validation

motion-mcp/
├── packages/               # 27 workspace packages (see architecture above)
├── apps/
│   ├── exercise-demo/      # Web studio demo
│   ├── exercise-mobile/    # Expo shell
│   └── web/                # Landing page
├── examples/next-app       # Reference integration with real .motion-mcp artifacts
├── pipeline/               # Offline Python bake pipeline (ARDY-ready)
├── skills/motion-mcp/      # Canonical 13-step agent workflow
└── tests/                  # 34 suites incl. conformance harness

Shipped — Phase A foundations

• ✅ svg-parser: DOM-based parsing replaces regex scanners everywhere
• ✅ scene-graph: SceneDoc v1 + deterministic motion grammar + validation + reference sampler
• ✅ Spec-to-code disconnect closed: experiences compile through SceneDoc into all four emitters
• ✅ ast-patcher: generated imports staged into real source files behind flags
• ✅ Conformance harness with cross-target goldens

Phase B: portability (in motion)

• ✅ @motion-mcp/player: ScenePlayer (transition graph, loop-aware seek, reduced-motion) + <motion-scene> web component

• ✅ @motion-mcp/exporters: Lottie JSON (full path→bezier incl. arcs) · animated SVG with baked keyframes

• ✅ export_animation MCP tool writing .motion-mcp/exports/

• ✅ @motion-mcp/riv-importer: binary reader per the public .riv spec (header, ToC backing-type bits, object stream) + import_riv tool

• ✅ @motion-mcp/capture: animated GIF output via headless rasterization — pure-TS LZW/GIF89a, zero browser dependency

• ✅ MP4/WebM assembly on the frame pipeline (capture_video, ffmpeg)

• ✅ Real visual previews: preview_animation returns rendered snapshots of staged diffs

• ✅ Keyframe + geometry decode from .riv: imported files render and animate through the player/GIF pipeline out of the box

Remaining:

1. Import fidelity extensions: parametric shapes (rect/ellipse), cubic mirrored/asymmetric vertices, gradient paints, strokes
2. Hosted share links for exported artifacts

Then — Phase C/D: ecosystem

5. Dynamic context engine (live re-index on file change)
6. Critique agent + motion-grammar dataset from accept/reject/edit telemetry
7. Stripe + Supabase billing mirror · hosted preview links (CI and npm publishing are live — see .github/workflows/)
8. Pixel-level visual cross-runtime diffing (headless Lottie renderer; stop-parity already enforced by verify_cross_runtime)
9. Pose-tracked rigging from video (BlazePose → bone hierarchy)

PRs welcome — see CONTRIBUTING.md for the ground rules (determinism, staged-diff review, honest receipts) and the release process. Security policy and threat model: SECURITY.md. Environment reference: .env.example. Release history: CHANGELOG.md.

Apache-2.0 © motion-mcp contributors