rive-mcp

rive-mcp

从 Claude 中创建、编辑、检查、渲染并实时预览 Rive（.riv）动画——无需 Rive 编辑器，也无需订阅。服务在你的机器上运行；少量外部调用列在网络访问下。

🌐 English | 日本語 | 简体中文 | 한국어 | Español | Français | Deutsch | Português (Brasil)

rive-mcp 是一个免费的 MCP（Model Context Protocol）服务，可让 Claude（或任何 MCP 客户端）完全控制 .riv 文件。与官方 Rive MCP（需要编辑器处于运行状态）或付费的第三方服务不同，它只需一个 .riv 文件即可运行——甚至可以通过直接序列化二进制格式，从头构建 .riv 文件。

渲染在无头 Chromium 中运行官方 Rive 运行时（@rive-app/canvas-advanced WASM），因此预览与运行时的输出一致，但限制中列出的 Canvas2D 差异除外。

此动画完全由 riv_create 生成——未使用 Rive 编辑器。

## 亮点

• 从 JSON 生成 .riv — 包括形状、渐变、嵌入式 PNG、文本（包括路径文本）、骨骼 + 蒙皮、IK、网格变形、带缓动的关键帧动画、多层状态机、监听器、事件、物理烘焙、粒子、嵌入式音频（WAV/MP3/FLAC），可由时间轴或状态机触发
• 从设计之初就具备专业品质 — 28 种语义化动作预设（pop-in、交错的 rise-in、breathing、stagger-in、parallax-drift、shimmer 等），振幅和缓动均经过专业调校；OKLCH 设计令牌生成器（riv_design_tokens）；动作质量 lint 规则（机械式线性运动、瞬移、缺少交错）；以及一次调用即可完成的评审循环（riv_critique：帧 + 客观指标 + 评分清单）
• 真正的矢量美术工作流 — 将 SVG（Figma/Illustrator/Iconify，或离线时使用 @twemoji/svg 等 npm SVG 素材集）作为真正的贝塞尔路径导入（riv_import_svg、riv_asset_search）；将现有 .riv 文件反编译为可编辑规格，包括渐变、混合模式和手动调校的动画轨道（riv_decompile）；场景规格还支持修剪路径（描绘效果）、剪切蒙版、混合模式（multiply 阴影、screen 发光）、沿路径运动、独奏，以及分离的贝塞尔控制柄
• 无损编辑现有 .riv — 更改任意属性、替换文本、删除子树（自动重新映射引用）
• 本地 Web Studio — 类似 Rive 编辑器的三面板 UI（层级结构 / 可点击选择并拖动的画布 / 检查器 / 时间轴），支持热重载；编辑会实时生效。还包括一个贝塞尔曲线编辑器，可手动调校关键帧缓动（拖动控制点、切换保持/线性/三次曲线、10 种一键预设）；一个状态机图视图（显示层/状态/转换的节点图，包含 lint 检查结果和实时播放状态高亮）；以及一个洋葱皮叠加层（显示周围 0-5 帧，便于快速检查动作）
• Studio 持续进化 — 支持拖放替换嵌入式资源图片（无损替换）、多画板标签页、命名快照的保存/恢复/删除、使用框选和 Shift-点击进行多选并可成组拖动，以及使用 Ctrl+C/V 复制粘贴；还提供骨骼叠加层，支持通过 FK 拖动摆姿势并直接烘焙为关键帧
• 人与 AI 协作循环 — Studio 中提供双向 Agent 聊天：你输入反馈（会附上当前选择项/画板/动画/时间），AI 通过 riv_studio_notes 获取反馈、修复文件，并在同一对话线程中回复；浏览器会即时更新
• 自动为角色绑定骨骼 — 一次调用即可将角色 PNG 转换为带骨骼绑定的 .riv，包含分割部件、带骨骼蒙皮的头部网格、眨眼、待机/开心动画和状态机
• 数据绑定与流水线工具 — riv_inspect 可解码 ViewModel 定义、实例（含解析后的值）、枚举、转换器和绑定连线——数据绑定检查功能目前鲜有工具支持；riv_batch_render 可通过一次支持 glob 的调用导出多文件 × 多格式，适用于 CI；riv_ab_compare 可将两个文件合成为并排显示、带标签的 GIF/APNG，用于设计评审
• 端到端测试 — test/e2e.mjs 会启动服务，并通过 JSON-RPC 调用其工具，处理 samples/vehicles.riv；在这些测试中，生成的文件会由官方运行时加载、渲染并驱动状态机

工具（32）

工具	功能
riv_list	递归查找 .riv 文件（大小、格式版本）
riv_inspect	完整元数据：画板、动画（时长/fps/循环）、状态机及输入，以及数据绑定结构（使用该功能时，包括 ViewModel 定义、含解析值的实例、枚举、转换器、绑定连线）
riv_lint	静态诊断：损坏的引用、过大的嵌入资源、无法到达的状态机状态、无条件自转换（有无限循环风险）、未使用的输入、轨道最后一个关键帧上的缓动被静默丢弃，以及运动质量规则（全线性动画造成的“机器人式”运动、物体瞬移、缺少错峰动画、单向缩放）
riv_render_frame	将任意时刻渲染为 PNG（内嵌图像 + 文件）
riv_render_gif	将动画转换为预览 GIF
riv_render_apng	导出动态 PNG——24 位色彩 + Alpha 透明度（可在 GitHub 上播放）
riv_render_video	将动画或状态机录制为 WebM 视频
riv_render_sprites	精灵图 PNG + JSON 元数据（适用于游戏引擎）
riv_batch_render	一次调用渲染一组任务——单个文件或 glob——输出 png/gif/apng/webm/sprites；支持按任务隔离错误并生成计时报告，专为 CI 构建
riv_play_state_machine	设置/触发输入 → 推进 → 状态转换报告（+ 可选帧捕获）
riv_generate_code	使用真实画板/SM/输入名称生成集成代码（React / JS / Vue / Svelte / Flutter）
riv_create	根据 JSON 场景规范构建 .riv——使用官方运行时验证，并返回预览。支持带贝塞尔控制柄的顶点、弹性缓动、渐变、烘焙物理效果、粒子，以及语义化运动预设（{"preset":"pop-in","target":"card"} 会在服务端展开为经过专业调校的关键帧——入场/退场/强调/环境循环，并支持对组使用 stagger）。还可嵌入音频（WAV/MP3/FLAC），并在时间轴帧或状态机进入时触发——AudioAsset/AudioEvent 会正确写入，但只能在使用 GPU 的 Rive 运行时中播放，无法在此服务自身的预览中播放
riv_design_tokens	设计前生成设计令牌：经过 OKLCH 协调的调色板（+WCAG 对比度）、渐变配色、Material-Motion 时长与缓动角色、间距/圆角/字体比例——根据种子颜色 + 风格情绪确定性生成
riv_import_svg	SVG → Rive 贝塞尔形状（Figma/Illustrator 导出内容、图标、插画）：完整三次曲线顶点、多轮廓路径、渐变、描边、嵌套变换——让 AI 创作专业作品，而不是用基本图元绘制。片段可通过 imports 接入 riv_create
riv_asset_search	搜索 Iconify 的约 20 万个专业设计图标，并直接将图标作为 Rive 形状导入（需要网络）
riv_lottie_import	Lottie/bodymovin JSON → Rive 场景片段——导入 LottieFiles 海量免费专业动画资源库中的美术素材和动画编排：带关键帧的变换（精确保留贝塞尔缓动曲线，而非用预设近似）、路径变形（逐顶点关键帧）、形状/空对象/预合成图层、渐变、修剪路径绘制效果、可见性区间。不支持的内容（文本图层、蒙版、轨道遮罩等）会计数，不会被静默丢弃
riv_decompile	.riv → 可编辑场景规范：研究或改编专业文件（贝塞尔路径、渐变、独奏、修剪路径、带命名缓动的动画）；不支持的类型会计数，不会被静默丢弃
riv_critique	一次调用即可生成评审包，让 VLM 直观查看运动效果：胶片条（从左到右排列帧）、洋葱皮叠加（运动轨迹）、运动报告（每个动画对象的净位移向量）、客观指标（贝塞尔比例、调色板标记、缓动分布）+ lint 结果 + 固定的 7 轴评分清单，包含空间/方向一致性（每个运动对象是否朝向其美术作品的正面移动？透视是否一致？）
riv_edit	无损编辑现有 .riv 文件：设置属性、替换指定文本、删除子树、添加/替换/移除关键帧
riv_optimize	在不改变视觉输出的前提下缩小 .riv：移除之前编辑遗留的未引用插值器/事件/空轨道；对严格线性片段中的冗余关键帧进行精简（Douglas-Peucker，确保缓动安全——绝不修改三次曲线/保持段）；通过 dryRun 报告优化方案
riv_extract_assets	从 .riv 中提取嵌入的图像/字体
riv_visual_diff	对两个 .riv 文件进行像素差异比较，并生成高亮差异图
riv_ab_compare	在相同条件下渲染两个 .riv 文件，并生成带标签的并排（或上下堆叠）GIF/APNG，供人工评审——riv_visual_diff 衡量像素级差异，而这个工具用于直观比较两个并排播放的不同内容
riv_dump	底层二进制结构转储（typeKeys / 属性 / 层级）
riv_slice_image	按多边形从 PNG 中裁切角色部件（用于剪纸式绑定）
riv_rig_character	一次调用即可将角色 PNG 转换为完整绑定的 .riv
riv_diff	对两个 .riv 文件进行结构差异比较
riv_studio	本地 Web Studio：采用 Rive 编辑器风格的深色 UI——层级树、画布选择/拖动/调整大小、检查器、关键帧时间轴编辑、贝塞尔曲线编辑器（拖动控制点、保持/线性/三次曲线、10 种缓动预设）、状态机图视图（节点图、转换详情、lint 高亮状态、实时播放高亮）、洋葱皮叠加、撤销/重做、播放速度、一键导出（PNG/APNG/GIF/WebM）、实时预览 + 热重载、EN/JA。share: true 还会通过不可猜测的令牌 URL 开启只读局域网视图（仅支持播放/拖动播放进度/状态机输入；可编辑的 Studio 仍留在 127.0.0.1）
riv_studio_notes	读取 Studio 的 Agent 聊天内容（自动附加上下文：选中项、画板、动画、播放时间），并向其中发送回复
riv_ui_detect	读取 UI 截图——或通过 svgPath 读取 Figma/Illustrator SVG：识别面板、文本段和图片，返回包含矩形、圆角半径和填充颜色的嵌套元素树，以及带编号的叠加 PNG。每个元素分别说明如何重建（vector-panel / vector-shape / vector-text / raster）以及外观类型（panel / text / image / line）。仅分析几何信息——无法区分按钮和卡片
riv_ui_prototype	再调用一次，即可将截图转换为动态 .riv：为每个检测到的元素指定角色，即可获得可用原型——能重建的元素使用矢量矩形，无法重建的元素使用图像切片，并为每种角色添加入场动画，同时支持卡片和按钮的悬停与按下效果。在颜色模型适用时，文本会使用真实 Alpha 蒙版裁切；不适用时，元素会原地淡入而非移动，警告中会说明原因
riv_setup	一键环境设置：将捆绑的 rive-design-guidelines 技能安装到 .claude/skills/（项目级）或 ~/.claude/skills/（用户级），使专业工作流自动触发——通过常规工具权限提示进行确认

截图 → 动画原型

riv_ui_detect 会将 UI 截图读取为带编号标注的元素树；为每个元素分配角色后，riv_ui_prototype 就会生成可运行的 .riv。面板会以可编辑的矢量矩形呈现，图片会作为图像切片呈现；如果颜色模型支持，文本会以真实的 Alpha 蒙版抠出；如果不支持，元素就会原地淡入而不是移动，并会说明原因。检测器的限制是经过测量的，而非凭空断言：请参阅 docs/ui-screenshot-to-prototype.md。

如果你还保留矢量源文件，请在同一组工具中传入 svgPath，而不是 imagePath，可以使用 Figma 中的右键 → Copy as SVG，或任何 Illustrator 导出文件。这样就无需估算：文件中的矩形、填充、圆角半径和父子树都会被读取；图稿会保留其真实的贝塞尔顶点；<text> 会变为可编辑的 Rive 文本（传入 fonts 即可使用设计稿指定的字体；缺少字形的文本段会烘焙为图片，而不是变成豆腐块，并且始终会发出警告）；嵌入的 <image> 数据会变为图像资源；Figma 图层名称会作为角色提示传入。除非你选择设置 FIGMA_TOKEN，否则不会通过网络获取任何内容；设置后会启用 figmaUrl 参数，可直接从 Figma REST API 获取一帧。未设置该变量时，传入此参数会报错且不会发出请求，其他工具也不会读取该变量。自 2023 年起，Rive 编辑器就支持粘贴 SVG；这两次调用的额外之处在于无需编辑器或人工介入，而且角色会一并带来动画效果——入场、环境循环以及悬停／按压状态。

展示案例：专业素材，专业动画

流水线端到端构建了四个示例场景，每个场景都可以通过 node samples/<name>/build-scene.mjs 重新构建：

• samples/weather-widget/ — 上方的主视觉动画：一个 UI 天气卡片，在晴天 → 下雨（伴有闪电）→ 晴天之间循环，全部呈现在一条循环时间轴上。以 SVG 格式导入 Twemoji 太阳／云／闪电，颜色来自 riv_design_tokens，环境动画来自预设，所有内容都裁剪在卡片范围内。
• samples/cosmic-journey/ — 每一件图稿都经过专业设计（Twemoji 火箭、环形行星、月亮、星星、彗星——通过 npm 获取 SVG，并使用 riv_import_svg 转换）；颜色来自 riv_design_tokens，动画来自预设，通过 riv_critique 循环固定构图。
• samples/night-delivery/ — 重新混编专业 .riv 文件：使用 riv_decompile 提取 Rive 官方卡车（手绘贝塞尔图稿及精细调整过的车轮／车身动画轨道），并将其与 Twemoji 月亮、滚动道路和采用 screen 混合模式的车灯光束组合成新的夜景。
• samples/launch-success/ — 手工编写的 SVG + 令牌 + 预设 + TrimPath 绘制动画 + 粒子 + intro→idle 状态机。

Twemoji 图稿 © Twitter/X 及贡献者，CC-BY 4.0；卡车图稿来自 Rive 官方示例文件。

设计质量指南

如果客户端只是随意编写场景规范，riv_create 的输出可能会看起来像扁平的“AI 占位”形状。服务端会从结构上保证质量——对于任何复杂场景，建议采用以下流程：

1. riv_design_tokens → 仅使用返回的调色板／渐变／时长／缓动（绝不自行编造原始十六进制颜色或临时设定时间）
2. riv_create → 尽可能使用运动 presets，而不是手动编写关键帧
3. riv_critique → 检查各帧，按 7 个维度的检查清单评分，修正任何低于 4 分的项目，然后重新运行（至少两次）

同一工作流以及手动创作的技巧规则（贝塞尔曲线、缓动语义、绑定）也通过 rive-design-guidelines MCP 提示词提供。它还在 6 个专门章节中包含数值方案（间距／时间标记、构图与分层规则、应避免的反模式）。对于不支持 MCP 提示词的客户端，还提供了便携式技能文件：skills/rive-design-guidelines/SKILL.md。

快速开始

Claude Code 插件（推荐） — 安装一次即可获得 MCP 服务、设计指南技能和 rive-designer Agent：

/plugin marketplace add ODU33104/rive-mcp
/plugin install rive-mcp@rive-tools

或者通过 npm 安装：

# Register with Claude Code (user scope = available in every project)
claude mcp add --scope user rive -- npx -y rive-mcp-server

或者先全局安装：

npm install -g rive-mcp-server
claude mcp add --scope user rive -- rive-mcp

或者从源代码运行：

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

要检查注册状态，请运行 claude mcp list：rive 应显示为 Connected。注册后重启 Claude Code，然后让它对某个文件夹运行 riv_list，以确认工具能够响应。

系统会按以下顺序自动检测基于 Chromium 的浏览器（如果已经安装 Chrome 或 Edge，则无需另行安装）：

1. RIVE_MCP_CHROME 环境变量（Chrome／Edge 可执行文件的路径）
2. Playwright 浏览器缓存
3. 已安装的 Chrome → Edge

需要 Node.js 20+ 和基于 Chromium 的浏览器（Chrome、Edge 或 Chromium）。如果未检测到浏览器，请将 RIVE_MCP_CHROME 环境变量设为可执行文件的路径。

工具参数中的相对路径将相对于启动 MCP 服务时所在的工作目录解析。如有疑问，请使用绝对路径。

Studio：人与 AI 协作

riv_studio 会打开一个本地网页，供用户检查、直接编辑并请求修改 AI 创建的内容（包含首次运行指南，界面提供英文／日文）：

1. 让 AI 创建 —“创建一个弹跳球 .riv 文件，并用 riv_studio 打开”
2. 动手调整 —在画布上点击／拖动对象，在检查器中调整数值和颜色（实时生效）
3. 向 AI 提出要求 —在 Agent 面板中输入较大的修改，然后在聊天中说“查看 Studio 备注”
4. AI 编辑文件时，浏览器会立即热重载，并在同一聊天中回报所做的修改

即使没有场景 JSON 也能使用：任何 .riv 文件都可以通过层级面板和检查器逐项编辑属性。

功能概览

采用你熟悉的编辑器布局——Studio 遵循官方 Rive 编辑器的操作模式：可切换 Design / Animate 模式；右键点击 Hierarchy 面板，可使用 Expand All / Collapse All / Deep Expand / Deep Collapse，并可按名称筛选；左侧面板底部设有 Data / Assets / Animations / Agent 折叠面板；最底部是 Console / Problems / Changes 状态栏（Problems 使用与 riv_lint 相同的静态检查，点击检查结果即可跳转到状态机图中的对应位置）。

在你预期的位置创建关键帧——在 Animate 模式下，每个可制作动画的检查器行都会出现一个菱形关键帧按钮，有三种状态：空心（没有动画轨道）、蓝色描边（已有动画，但播放头下没有关键帧）、蓝色实心（此处已有关键帧）。点击即可在播放头位置添加或取消关键帧。下方的点位图用于查看和重新排列现有内容。

多个画板与快照——通过标签栏在文件的各个画板之间切换，并保存、还原或删除编辑内容的命名快照——快照历史独立于撤消/重做记录。

时间轴 / 点位图——按轨道显示关键帧，并可控制跳转、缩放和播放速度。使用框选或 Shift-单击跨轨道选择，拖动即可整体移动所选关键帧；使用 Ctrl+C/V 复制/粘贴，内容将锚定在播放头位置（曲线也会一并保留）。

贝塞尔曲线编辑器——选择一段关键帧范围，拖动控制点，或应用 10 种缓动预设之一。可将任意区段切换为保持 / 线性 / 三次曲线。

状态机图视图——以节点图形式显示图层、状态和转换；点击转换即可查看其持续时间、exitTime 和条件。集成了 Lint 检查：无法到达的状态标为红色，无条件自转换标为黄色，播放期间活动状态会发光。

状态机试验台——在浏览器中切换布尔输入并触发触发器，观察转换过程。

洋葱皮——以基于距离的透明度显示周围 0–5 帧的残影，一眼即可检查运动轨迹。

直接编辑——在层级面板或画布上选择对象，然后在检查器中编辑位置 / 旋转 / 缩放 / 颜色 / 文本，并支持撤消/重做。

骨骼叠加与姿势调整——在画布上查看骨骼，并随播放头更新（拖动播放头、播放和暂停时，都会显示运行时计算出的姿势）；暂停时可拖动旋转骨骼（FK），并将当前姿势烘焙为关键帧。

Agent 聊天——这是双向对话，而不是建议框。发送的消息会附带当前选区、画板、动画和播放头时间；AI 会通过 riv_studio_notes 获取消息，并将结果发回同一对话线程，让你无需离开 Studio 就能查看更改内容。

一键导出

点击 Studio 工具栏中的 PNG / APNG / GIF / WebM，即可即时渲染当前动画——快速预览导出无需经过 MCP 往返。

角色动画

将单张角色 PNG 转换为自然动效的 .riv：

• riv_slice_image 按多边形裁出耳朵、尾巴等部位，riv_rig_character 一次调用即可组装完整骨骼：枢轴组、用于倾斜的无缝双骨骼头部网格、矢量眼睑眨眼、待机/开心动画，以及 happy 触发器
• 也可以用 riv_create 手动组合：嵌入图像、带逐顶点关键帧的网格、采用距离加权蒙皮的骨骼链、IK 约束

示例提示词

适用于克隆仓库的示例。使用 npm 版本时，示例位于软件包的 <npm root -g>/rive-mcp-server/samples/ 目录中（全局安装），也可以使用你自己的 .riv 文件路径。

• “列出 samples/ 中的 riv 文件并检查 vehicles.riv”
• “将 curves 动画渲染为 GIF”
• “创建一个夜空中飘雪的 riv，并在工作室中打开”
• “为 characters/cat.png 添加骨骼绑定——耳朵和尾巴应能活动，点击时它应显得很开心”
• “查看工作室备注”（在工作室 UI 中输入反馈后）
• “为此文件编写 React 集成代码”

开发

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 记录了写入器所用 .riv 二进制格式的逆向工程知识（typeKeys/propertyKeys 根据 vendor/rive-defs/defs.json 中随附的官方 rive-runtime 类型定义解析）。

限制

• 运行时 API 不提供文本运行枚举功能（但可以按名称访问）
• GIF 输出不支持透明度（会合成到背景色上）
• Canvas2D 预览渲染器可能会显示文件中实际不存在的网格接缝（WebGL/Skia 渲染正常）
• fill.feather/stroke.feather（矢量模糊）可以正确写入 .riv，但此服务的 Canvas2D 预览管线不会渲染它——只有 GPU Rive Renderer 支持此功能
• 不会生成 Luau 脚本和 Layout 引擎（运行时规范仍在变动）
• 截图检测（riv_ui_detect）对细微的像素变化很敏感：无损 PNG 重新编码后图像相同，但 ±2 RGB 噪点会导致大多数矢量面板被重新分类，并使元素数量接近翻三倍。每个纯色填充在交付前都会与截图进行测试渲染，因此最终保留的内容经过测量，能够与截图匹配——代价是在照片较多的页面上，保真度优先于可编辑性，大多数元素会被处理为只能淡入淡出的切片。测量数据和其余限制见 docs/ui-screenshot-to-prototype.md

网络访问

此服务在本地运行。仅在以下情况下会发起外部请求：

• riv_asset_search：Iconify API（api.iconify.design）
• riv_ui_detect / riv_ui_prototype 中的 figmaUrl：Figma REST API（api.figma.com），且仅当服务环境中设置了 FIGMA_TOKEN 时才会请求。未设置时不会发起请求
• riv_studio 使用 share: true：提供同一 LAN 上其他设备可访问的只读视图。这是传入流量，不是外部调用
• 首次运行 npx -y rive-mcp-server 时，会从 npm 下载软件包

许可证

可免费使用（个人及商业用途），但并非开源。这是源代码可用的免费软件：

• ✅ 可自由使用此软件；生成的 .riv 文件和代码均归你所有，不受限制
• ❌ 不得修改、再分发或创作衍生作品
• ❌ 不得逆向工程；不得借助 AI 分析、提取或复现代码（包括将代码用作训练数据）

确切条款见 LICENSE。随附的第三方组件：Inter 字体（OFL 1.1）、Rive 运行时和类型定义（MIT，© Rive, Inc.）。

rive-mcp 是非官方工具，与 Rive, Inc. 无关联，也未获其认可。