RiveMCP

MCP server for programmatically creating and editing Rive animation files. Generates binary .riv files from a high-level builder API, exposed as MCP tools for LLM-driven animation authoring.

Features

• 132 MCP tools covering all Rive capabilities
• 267 Rive runtime types — full coverage of the Rive binary format
• Import + roundtrip — load existing .riv files, modify, re-export
• Edit tools — query, update, and delete objects after creation
• 14 easing presets — ease, spring, bounce, material design, and more
• Physics engine — compile-time gravity, bounce, wind, and spring forces
• Prefab library — rocks, dust, sparks, rain, snow, leaves, backgrounds
• Scene composer — describe a full animated scene in JSON, get a .riv in one call

Quick Start

One-click install for Claude Desktop (recommended)

1. Download rivemcp-<version>.mcpb from the Releases page.
2. Open Claude Desktop → Settings → Extensions → Install from file...
3. Select the .mcpb file. Done — no Node.js, no JSON editing, no path setup.

Manual install (other MCP clients)

npm install
npm run build

Add to your MCP client configuration:

{
  "mcpServers": {
    "rivemcp": {
      "command": "node",
      "args": ["dist/mcp/server.js"]
    }
  }
}

Or run in development mode:

npm run dev

Building the .mcpb bundle yourself

npm run build:mcpb

Produces rivemcp-<version>.mcpb in the repo root (~7 MB). Distribute that single file for one-click install.

Tool Categories

| Category | Tools | Description | |----------|-------|-------------| | Artboard | 3 | Create projects, artboards, list objects | | Shapes | 9 | Rectangles, ellipses, triangles, paths, groups | | Style | 7 | Fills, strokes, gradients, trim paths, dash paths, feather | | Edit | 6 | Query, update, and delete shapes/groups/text | | Animation | 3 | Keyframe animation with 14 easing presets | | State Machine | 12 | Layers, states, transitions, conditions, listeners | | Events | 3 | Custom events, open-URL events, custom properties | | Text | 3 | Text objects with styled runs | | Images | 2 | Embedded image assets | | Nested | 4 | Nested artboards for component reuse | | Bones | 6 | Bones, IK constraints, skinning | | Mesh | 1 | Mesh deformation | | Constraints | 1 | Transform constraints | | Scroll | 2 | Scroll and scroll-bar constraints | | ViewModel | 12 | Data enums, view models, instances, data binding | | Advanced | 44 | Layout, assets, scripting, organization, draw order | | HLAPI | 8 | Physics baking, prefabs, particles, scene composition | | Import/Export | 2 | Load existing .riv, export with validation |

Easing Presets

The add_keyframe tool accepts an easing parameter for named presets:

| Preset | Curve | Use Case | |--------|-------|----------| | linear | Constant speed | Rotation, continuous motion | | ease | Gentle S-curve | General purpose | | ease-in | Slow start | Elements leaving view | | ease-out | Slow end | Elements entering view | | ease-in-out | Slow both ends | Symmetric transitions | | material-standard | Material Design | Navigation transitions | | material-decelerate | Material decel | Incoming elements | | material-accelerate | Material accel | Outgoing elements | | spring | Overshoot | Playful interactions | | bounce-out | Settle bounce | Landing, drop effects | | snap | Fast then hold | Toggle, switch states | | anticipate | Pull-back start | Button press, launch | | smooth | Smooth S-curve | UI transitions | | smooth-out | Smooth decel | Fade-in | | smooth-in | Smooth accel | Fade-out |

High-Level Animation API (HLAPI)

Three abstraction layers for complex animations:

Layer 3: Scene Composer    compose_scene
  "Rockslide with mountains, 20 falling rocks, dust"

Layer 2: Prefabs           spawn_prefab, emit_particles
  "Spawn 20 rocks with random size/position"

Layer 1: Physics Bakers    bake_motion, bake_shake
  "Apply gravity, bounce at ground, wind gusts"

Layer 0: Core Tools        132 MCP tools
  Shapes, fills, keyframes, state machines...

Physics Forces

• Gravity — constant downward acceleration
• Ground bounce — collision with restitution and squash/stretch
• Wind — horizontal force with sinusoidal gusting
• Spring — Hooke's law oscillation toward an anchor point

Physics runs at compile time. Dense per-frame snapshots are compressed to sparse keyframes via Douglas-Peucker simplification (180 frames typically compress to 5-10 keyframes).

Prefab Library

Shapes: rock, dust_cloud, debris, spark, raindrop, snowflake, leaf, bubble Backgrounds: sky_gradient (day/dusk/night/storm), mountain_range, ground_plane, starfield

Edit Tools

Six tools for iterative design after initial creation:

| Tool | Description | |------|-------------| | get_object_info | Query any object's transform, geometry, fills, strokes | | update_object | Modify position, size, rotation, scale, opacity | | update_fill | Change fill color by index | | update_stroke | Change stroke color, thickness by index | | remove_object | Delete a shape, group, or text | | update_text | Update text content on a run |

Import / Roundtrip

load_riv → modify with tools → export_riv

The load_riv tool imports existing .riv files into the builder scene graph. Unmodified artboards are preserved byte-for-byte on re-export.

Demo Files

| File | Description | |------|-------------| | sample.riv | Basic shapes + keyframe animation | | expand-rect.riv | State machine click interaction | | ui-buttons.riv | Full UI dashboard: gradients, elastic easing, blend states, feather, trim paths | | flag-wave.riv | Mesh deformation + embedded image | | confetti-twist.riv | Mesh corner spiral animation | | rockslide-hlapi.riv | HLAPI physics, prefabs, and scene composition | | character-demo.riv | Bones, IK constraints, skinning | | data-bind-demo.riv | Toggle switch with cross-object color theme change |

Generate demos with:

npx tsx scripts/generate-sample.ts
npx tsx scripts/generate-ui-buttons.ts
npx tsx scripts/generate-data-bind-demo.ts

Viewer

Open viewer.html in a browser (via HTTP server) to preview .riv files. Supports drag-and-drop upload and a batch test grid for all demo files.

npx serve .
# Open http://localhost:3000/viewer.html

Development

npm test              # Run all tests
npm run build         # TypeScript compile
npm run dev           # Run MCP server with tsx
npm run extract-defs  # Regenerate rive-defs.json from rive-cpp

Architecture

src/
  core/           Binary .riv reader/writer, LEB128 encoding
  defs/           Rive type registry (from rive-cpp source)
  builder/        High-level scene graph API
  hlapi/          Physics engine, prefab library, scene composer
  mcp/            MCP server + 132 tools

License

All rights reserved. Commercial license required for use.