rive-mcp

# rive-mcp **Create, edit, inspect, render and live-preview Rive (`.riv`) animations from Claude — no Rive editor, no cloud, no subscription.** [日本語 README はこちら](./README.ja.md) rive-mcp is a free MCP (Model Context Protocol) server that gives Claude (or any MCP client) full control over `.riv` files. Unlike the official Rive MCP (which requires the editor running) or paid third-party servers, it works with nothing but a `.riv` file — and it can even **build `.riv` files from scratch** by serializing the binary format directly. Rendering runs the **official Rive runtime** (`@rive-app/canvas-advanced` WASM) inside headless Chromium, so what you see is exactly what ships.  <p align="center"><img src="docs/media/showcase-weather.gif" width="380" alt="Weather widget built by the tokens → pro-assets → presets → critique pipeline (artwork: Twemoji)"></p> <p align="center"><i>This animation was generated entirely by <code>riv_create</code> — no Rive editor involved.</i></p> ## Highlights - **Generate `.riv` from JSON** — shapes, gradients, embedded PNGs, text, bones + skinning, IK, mesh deformation, keyframe animation with easing, multi-layer state machines, listeners, events, physics baking, particles, embedded audio (WAV/MP3/FLAC) fired from the timeline or a state machine - **Pro-quality by construction** — 28 semantic motion presets (`pop-in`, staggered `rise-in`, `breathing`, `stagger-in`, `parallax-drift`, `shimmer`, …) with professionally tuned amplitudes/easings, an OKLCH design-token generator (`riv_design_tokens`), motion-quality lint rules (robotic linear movement, teleports, missing stagger), and a one-call critique loop (`riv_critique`: frames + objective metrics + scoring checklist) - **Real vector art pipeline** — import SVG (Figma/Illustrator/Iconify, or npm SVG sets like `@twemoji/svg` when offline) as true bezier paths (`riv_import_svg`, `riv_asset_search`), decompile existing `.riv` files into editable specs **including gradients, blend modes and hand-tuned animation tracks** (`riv_decompile`), plus trim paths (draw-on), clipping masks, blend modes (`multiply` shadows, `screen` glows), follow-path motion, solos and detached bezier handles in the scene spec - **Losslessly edit existing `.riv`** — change any property, swap text, delete subtrees (references auto-remapped); round-trip verified pixel-perfect - **Local web Studio** — Rive-editor-style 3-pane UI (hierarchy / canvas with click-select & drag / inspector / timeline) with hot reload; edits apply live. Also includes a **bezier curve editor** for hand-tuning keyframe easing (drag control points, hold/linear/cubic switching, 10 one-click presets), a **state machine graph view** (node graph of layers/states/transitions with lint findings and live-playback state highlighting), and an **onion skin** overlay (0-5 surrounding frames) for checking motion at a glance - **Studio keeps growing** — drag-and-drop image replacement for embedded assets (lossless swap), multi-artboard tabs, named snapshot save/restore/delete, dope-sheet marquee/Shift-click multi-select with grouped drag and Ctrl+C/V copy-paste, and a bone overlay with FK drag-to-pose that bakes straight to a keyframe - **Human ⇄ AI loop** — a two-way **Agent chat** in the Studio: you type feedback (with the current selection/artboard/animation/time attached), the AI picks it up via `riv_studio_notes`, fixes the file, and replies into the same thread; your browser updates instantly - **Auto-rig characters** — one call turns a character PNG into a rigged `.riv` with cutout parts, bone-skinned head mesh, eye blink, idle/happy animations and a state machine - **Data binding & pipeline tooling** — `riv_inspect` decodes ViewModel definitions, instances (with resolved values), enums, converters and bind wiring — data binding inspection that few tools support yet; `riv_batch_render` exports many files × formats in one glob-aware call for CI, and `riv_ab_compare` composites two files side by side into one labeled GIF/APNG for design review - **Everything verified** — generated files are loaded, rendered and state-machine-driven by the official runtime in E2E tests ## Tools (32) | Tool | What it does | |---|---| | `riv_list` | Recursively find `.riv` files (size, format version) | | `riv_inspect` | Full metadata: artboards, animations (duration/fps/loop), state machines and inputs, plus data-binding structure (ViewModel definitions, instances with resolved values, enums, converters, bind wiring) when the file uses it | | `riv_lint` | Static diagnostic: broken references, oversized embedded assets, unreachable state-machine states, unconditional self-transitions (infinite-loop risk), unused inputs, easing silently discarded on a track's last keyframe, **motion-quality rules** (all-linear "robotic" movement, teleporting objects, missing stagger, one-sided scale) | | `riv_render_frame` | Render any moment to PNG (inline image + file) | | `riv_render_gif` | Turn an animation into a preview GIF | | `riv_render_apng` | Animated PNG export — 24-bit color + alpha transparency (plays on GitHub) | | `riv_render_video` | Record an animation or state machine to WebM video | | `riv_render_sprites` | Sprite-sheet PNG + JSON metadata (for game engines) | | `riv_batch_render` | Render a list of jobs — single files or globs — to png/gif/apng/webm/sprites in one call; per-job error isolation and a timing report, built for CI | | `riv_play_state_machine` | Set/fire inputs → advance → state-transition report (+ optional frame captures) | | `riv_generate_code` | Integration code with real artboard/SM/input names (React / JS / Vue / Svelte / Flutter) | | `riv_create` | **Build a `.riv` from a JSON scene spec** — validated with the official runtime, returns a preview. Supports bezier-handled vertices, elastic easing, gradients, physics baking, particles, and **semantic motion presets** (`{"preset":"pop-in","target":"card"}` expands server-side into professionally tuned keyframes — entrances/exits/emphasis/ambient loops, with `stagger` for groups). Also embeds audio (WAV/MP3/FLAC) fired from timeline frames or state-machine entry — the AudioAsset/AudioEvent are written correctly but only play back in a GPU-backed Rive runtime, not this server's own preview | | `riv_design_tokens` | **Generate design tokens before designing**: OKLCH-harmonized palette (+WCAG contrast), gradient pairs, Material-Motion durations & easing roles, spacing/radius/type scales — deterministic from seed color + mood | | `riv_import_svg` | **SVG → Rive bezier shapes** (Figma/Illustrator exports, icons, illustrations): full cubic vertices, multi-contour paths, gradients, strokes, nested transforms — so the AI composes pro artwork instead of drawing with primitives. Fragments plug into riv_create via `imports` | | `riv_asset_search` | Search **Iconify's ~200k professionally designed icons** and import one directly as Rive shapes (needs network) | | `riv_lottie_import` | **Lottie/bodymovin JSON → Rive scene fragment** — pulls in LottieFiles' huge library of free professionally-animated assets art *and* choreography: keyframed transforms with exact bezier easing curves (not preset-approximated), path morphing (per-vertex keyframes), shape/null/precomp layers, gradients, trim-path draw-on, visibility windows. Unsupported bits (text layers, masks, mattes, …) are counted, not silently dropped | | `riv_decompile` | **.riv → editable scene spec**: study or remix professional files (bezier paths, gradients, solos, trim paths, animations with named easings); unsupported types are counted, not silently dropped | | `riv_critique` | **One-call review bundle that makes motion visible to a VLM**: a filmstrip (frames left→right), an onion-skin overlay (motion trails), a motion report (net displacement vector per animated object), objective metrics (bezier ratio, palette flags, easing distribution) + lint findings + a fixed 7-axis scoring checklist incl. spatial/directional coherence (does each mover travel toward its artwork's front? is the perspective consistent?) | | `riv_edit` | Lossless editing of existing `.riv` files: set properties, swap named text, delete subtrees, **add/replace/remove keyframes** | | `riv_optimize` | Shrink a `.riv` without changing its visual output: remove unreferenced interpolators/events/empty tracks left over from prior edits, thin redundant keyframes on strictly-linear runs (Douglas-Peucker, easing-safe — cubic/hold segments are never touched), with a `dryRun` report of the plan | | `riv_extract_assets` | Extract embedded images/fonts from a `.riv` | | `riv_visual_diff` | Pixel diff of two `.riv` files with a highlighted diff image | | `riv_ab_compare` | Render two `.riv` files under identical conditions into one labeled side-by-side (or stacked) GIF/APNG for human review — where riv_visual_diff measures a pixel-level delta, this one is for eyeballing two different things playing next to each other | | `riv_dump` | Low-level binary structure dump (typeKeys / properties / hierarchy) | | `riv_slice_image` | Cut character parts out of a PNG by polygon (for cutout rigging) | | `riv_rig_character` | **Character PNG → fully rigged `.riv` in one call** | | `riv_diff` | Structural diff between two `.riv` files | | `riv_studio` | **Local web Studio**: Rive-editor-style dark UI — hierarchy tree, canvas select/drag/resize, inspector, keyframe timeline editing, **bezier curve editor** (drag control points, hold/linear/cubic, 10 easing presets), **state machine graph view** (node graph, transition details, lint-highlighted states, live playback highlighting), **onion skin** overlay, undo/redo, playback speed, one-click export (PNG/APNG/GIF/WebM), live preview + hot reload, EN/JA | | `riv_studio_notes` | Read the Studio's Agent chat (with auto-attached context: selection, artboard, animation, playback time) and post replies back into it | | `riv_ui_detect` | **Read a UI screenshot** — or, with `svgPath`, a Figma/Illustrator SVG: finds panels, text runs and pictures, returns a nested element tree with rects, corner radii and fill colours plus a numbered overlay PNG. Each element says how it would be rebuilt (`vector-panel` / `vector-shape` / `vector-text` / `raster`) and what it looks like (`panel` / `text` / `image` / `line`) as separate fields. Geometry only — it does not know a button from a card | | `riv_ui_prototype` | **Screenshot → animated `.riv` in one more call**: assign a role to each detected element and get a working prototype — vector rectangles where they can be rebuilt, image slices where they cannot, an entrance per role, hover and press on cards and buttons. Text is cut out with a real alpha matte where the colour model holds; where it does not, the element fades in place instead of moving, and the warnings say so | | `riv_setup` | **One-call environment setup**: installs the bundled `rive-design-guidelines` skill into `.claude/skills/` (project) or `~/.claude/skills/` (user) so the pro workflow auto-triggers — confirmation happens via the normal tool-permission prompt | ### Screenshot → animated prototype  `riv_ui_detect` reads a UI screenshot into an element tree with a numbered overlay; assign a role to each element and `riv_ui_prototype` writes a working `.riv`. Panels come back as editable vector rectangles, pictures as image slices, and text is cut out with a real alpha matte where the colour model holds — where it does not, the element fades in place instead of moving, and says so. The detector's limits are measured rather than asserted: see [docs/ui-screenshot-to-prototype.md](docs/ui-screenshot-to-prototype.md). **If you still have the vector source, pass `svgPath` instead of `imagePath`** to the same two tools — Figma's right-click → Copy as SVG, or any Illustrator export. Nothing is estimated then: rectangles, fills, corner radii and the parent/child tree are read out of the file, artwork keeps its real bezier vertices, `<text>` becomes editable Rive text (pass `fonts` for the design's own faces; a run whose glyphs are missing is baked as a picture rather than as tofu, always with a warning), embedded `<image>` data becomes an image asset, and Figma layer names arrive as role hints. Nothing is fetched over the network — unless you opt in by setting `FIGMA_TOKEN`, which enables a `figmaUrl` argument that pulls one frame straight from Figma's REST API; without the variable that argument errors and no request is made, and no other tool reads it. Rive's editor has accepted pasted SVGs since 2023; what these two calls add is that no editor and no person are in the loop, and that the roles bring the motion — entrances, ambient loops and hover/press states — with them. ### Showcases: professional assets in, professional motion out Four sample scenes are built end-to-end by the pipeline, each rebuildable with `node samples/<name>/build-scene.mjs`: - [`samples/weather-widget/`](samples/weather-widget/) — the hero animation above: a UI weather card that cycles sunny → rain (with a lightning flash) → sunny on one looping timeline. Twemoji sun/cloud/bolt imported as SVG, colors from `riv_design_tokens`, ambient motion from presets, everything clipped to the card. - [`samples/cosmic-journey/`](samples/cosmic-journey/) — **every piece of artwork is professionally designed** (Twemoji rocket, ringed planet, moon, stars, comet — fetched as SVG via npm and converted with `riv_import_svg`); colors from `riv_design_tokens`, motion from presets, composition fixed through the `riv_critique` loop. - [`samples/night-delivery/`](samples/night-delivery/) — **remixes a professional `.riv`**: Rive's official truck (hand-drawn bezier art *and* its hand-tuned wheel/body animation tracks) is extracted with `riv_decompile` and composed into a new night scene with a Twemoji moon, scrolling road and a `screen`-blended headlight beam. - [`samples/launch-success/`](samples/launch-success/) — hand-authored SVG + tokens + presets + TrimPath draw-on + particles + intro→idle state machine. <p align="center"><img src="samples/cosmic-journey/cosmic.gif" width="420" alt="Cosmic Journey — all artwork imported from professionally designed SVGs"><br><img src="samples/night-delivery/delivery.gif" width="420" alt="Night Delivery — professional .riv decompiled and remixed"></p> Twemoji artwork © Twitter/X and contributors, [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/); truck artwork from Rive's official example files. ### Design quality guidance `riv_create` output can look like flat "AI placeholder" shapes if a client just wings the scene spec. The server bakes quality in structurally — the recommended flow for any non-trivial scene is: 1. `riv_design_tokens` → use only the returned palette/gradients/durations/easings (never invent raw hex or ad-hoc timings) 2. `riv_create` with motion `presets` instead of hand-authored keyframes wherever one fits 3. `riv_critique` → look at the frames, score the 6-axis checklist, fix anything below 4, re-run (at least twice) The same workflow plus hand-authoring craft rules (bezier curves, easing semantics, rigging) is exposed as the `rive-design-guidelines` MCP prompt. It also carries numeric recipes (spacing/timing tokens, composition & layering rules, anti-patterns to avoid) across 6 dedicated sections. For clients without MCP prompts support, it ships as a portable skill file at [`skills/rive-design-guidelines/SKILL.md`](skills/rive-design-guidelines/SKILL.md). ## Quick start **Claude Code plugin (recommended)** — one install gets the MCP server, the design-guidelines skill, and the `rive-designer` agent: ``` /plugin marketplace add ODU33104/rive-mcp /plugin install rive-mcp@rive-tools ``` Or install from npm: ```bash npm install -g rive-mcp-server # Register with Claude Code (user scope = available in every project) claude mcp add --scope user rive -- rive-mcp ``` Or run from source: ```bash git clone https://github.com/ODU33104/rive-mcp.git cd rive-mcp npm install npm run build claude mcp add --scope user rive -- node /absolute/path/to/rive-mcp/dist/index.js ``` A Chromium-based browser is auto-detected in this order (usually nothing to install): 1. `RIVE_MCP_CHROME` env var (path to Chrome/Edge executable) 2. Playwright browser cache 3. Installed Chrome → Edge Requires Node.js 20+. ## The Studio: human ⇄ AI collaboration `riv_studio` opens a local web page where a human can inspect, directly edit, and request changes to whatever the AI built (first-run guide included, UI in English/Japanese): 1. **Let the AI build** — "create a bouncing-ball riv and open it with riv_studio" 2. **Touch it** — click/drag objects on the canvas, tweak numbers & colors in the inspector (applies live) 3. **Ask the AI** — type bigger changes into the **Agent** panel, then say "check the studio notes" in chat 4. When the AI edits the file, the browser hot-reloads instantly — and it writes back what it changed, in the same chat Works without a scene JSON too: any `.riv` can be edited property-by-property through the hierarchy + inspector.  ### Feature tour **Laid out like the editor you already know** — the Studio follows the official Rive editor's operating model: a **Design / Animate** mode switch, a Hierarchy panel with `Expand All` / `Collapse All` / `Deep Expand` / `Deep Collapse` on right-click and a name filter, `Data / Assets / Animations / Agent` accordions along the bottom of the left panel, and a `Console / Problems / Changes` status bar at the very bottom (Problems is wired to the same static checks as `riv_lint`, and clicking a finding jumps to it in the state-machine graph). **Keys are created where you'd expect them** — in Animate mode every animatable inspector row grows a diamond key button with three states: hollow (no track), outlined blue (animated but no key under the playhead), filled blue (keyed here). Click to key or unkey at the playhead. The dope sheet below is for reading and rearranging what's already there. **Multiple artboards & snapshots** — switch between a file's artboards with a tab bar, and save, restore or delete named snapshots of your edits — a separate history from undo/redo.  **Timeline / dope sheet** — per-track keyframes with seek, zoom and playback-speed control. Marquee- or Shift-click to select across tracks, drag a whole selection of keyframes together, and copy/paste with Ctrl+C/V anchored at the playhead (curves carry over).   **Bezier curve editor** — pick a keyframe span, drag the control points, or apply one of 10 easing presets. Switch any span between hold / linear / cubic.  **State machine graph view** — layers, states and transitions as a node graph; click a transition to see its duration / exitTime / conditions. Lint-integrated: unreachable states are red, unconditional self-transitions yellow, and the active state glows during playback.  **State machine playground** — flip bool inputs and fire triggers from the browser to watch transitions happen.  **Onion skinning** — ghost the surrounding 0–5 frames with distance-based opacity to check motion arcs at a glance.  **Direct editing** — select in the hierarchy or on the canvas, then edit position / rotation / scale / colors / text in the inspector with undo/redo.  **Bone overlay & posing** — see the bone skeleton over the canvas, drag to rotate a bone (FK) while paused, and bake the current pose into a keyframe.  **Agent chat** — a two-way conversation, not a suggestion box. Your message ships with the current selection, artboard, animation and playhead time attached; the AI picks it up via `riv_studio_notes` and posts its result back into the same thread, so you can see what it changed without leaving the Studio.  ## One-click export Click PNG / APNG / GIF / WebM in the Studio toolbar to render the current animation on the spot — no MCP round-trip needed for a quick preview export.  ## Character animation Turn a single character PNG into a naturally moving `.riv`: - `riv_slice_image` cuts out ears/tail/etc. by polygon, `riv_rig_character` assembles the whole rig in one call: pivot groups, a seamless 2-bone head mesh for tilting, vector eyelid blink, idle/happy animations and a `happy` trigger - Or compose manually with `riv_create`: image embedding, grid meshes with per-vertex keyframes, bone chains with distance-weighted skinning, IK constraints ## Example prompts - "List the riv files in `samples/` and inspect vehicles.riv" - "Render the `curves` animation as a GIF" - "Create a riv of falling snow over a night sky and open it in the studio" - "Rig `characters/cat.png` — ears and tail should move, and it should look happy on click" - "Check the studio notes" *(after typing feedback into the Studio UI)* - "Write the React integration code for this file" ## Development ```bash npm run build # vendor runtime assets + tsc npm run test:e2e # spawns the real server, exercises all 32 tools over JSON-RPC ``` `docs/riv-format.md` documents the reverse-engineered knowledge of the `.riv` binary format used by the writer (typeKeys/propertyKeys resolved from the official `rive-runtime` type definitions vendored in `vendor/rive-defs/defs.json`). ## Limitations - Text-run enumeration is not exposed by the runtime API (access by name works) - GIF output has no transparency (composited on a background color) - The Canvas2D preview renderer can show mesh seams that don't exist in the file (WebGL/Skia render clean) - `fill.feather`/`stroke.feather` (vector blur) writes correctly to the `.riv` but isn't rendered by this server's Canvas2D preview pipeline — only a GPU Rive Renderer supports it - Luau scripting and the Layout engine are not generated (runtime spec still moving) - Screenshot detection (`riv_ui_detect`) is sensitive to small pixel changes: a lossless PNG re-encode is identical, but ±2 RGB noise reclassifies most vector panels and can nearly triple the element count. Every flat fill is test-rendered against the screenshot before it ships, so what survives is measured to match — the cost is that fidelity wins over editability on photo-heavy pages, where most elements come back as slices that only fade. See [docs/ui-screenshot-to-prototype.md](docs/ui-screenshot-to-prototype.md) for the measured numbers and the rest of the limits ## License **Free to use** (personal & commercial) — but **not open source**. This is source-available freeware: - ✅ Use the software freely; the `.riv` files and code it generates are yours without restriction - ❌ No modification, no redistribution, no derivative works - ❌ No reverse engineering; no AI-assisted analysis, extraction or reproduction of the code (including use as training data) See [LICENSE](./LICENSE) for the exact terms. Bundled third-party components: Inter font (OFL 1.1), Rive runtime & type definitions (MIT, © Rive, Inc.). *rive-mcp is an unofficial tool and is not affiliated with or endorsed by Rive, Inc.*