MCP Server - UpstandPlatform/OpenRive GitHub Wiki

OpenRive includes a Model Context Protocol server, so AI assistants can create and edit Rive animations for you: "Make a loading animation with three bouncing dots in brand purple that pauses when clicked."

It runs over stdio or the web app's authenticated Streamable HTTP endpoint and uses the same storage as the app. Open the returned editor link to watch the result appear live.

The web app's AI & API page is the central connection surface. It shows the correct MCP endpoint for the current edition, lets signed-in cloud and self-hosted users create or revoke scoped API keys, and explains the key-free local CLI or desktop connection.

The editor and MCP server share the same Rive editing core. Current tools include data properties, transitions, listeners and events, 1D blend states, and distance constraints; get_project reports those authored elements so an assistant can inspect the resulting file before making another edit.

The repo includes .mcp.json. Open the project in Claude Code and approve the openrive server.

Add a server entry (adjust the path):

{
  "mcpServers": {
    "openrive": {
      "command": "bun",
      "args": ["/path/to/OpenRive/apps/cli/src/mcp-server.ts"],
      "env": { "OPENRIVE_DATA_DIR": "/path/to/openrive/data" }
    }
  }
}

With PostgreSQL, set DATABASE_URL in env instead of OPENRIVE_DATA_DIR.

Using Docker? Run it inside the container:

{ "command": "docker", "args": ["compose", "-f", "/path/to/OpenRive/docker-compose.yml", "exec", "-T", "openrive", "openrive", "mcp"] }

Authenticated self-hosted and cloud deployments expose MCP at /api/mcp. Create a short-lived, user-scoped bearer key from a signed-in browser session:

curl -sS -X POST https://openrive.example.com/api/mcp/keys \
  -H 'content-type: application/json' \
  -H 'cookie: openrive.session_token=…' \
  -d '{"name":"Claude","expiresIn":7776000}'

The response contains the secret once. Store it in the AI client and connect its Streamable HTTP transport to https://openrive.example.com/api/mcp with Authorization: Bearer <key>. Keys can be listed with GET /api/mcp/keys and revoked with DELETE /api/mcp/keys and {"keyId":"…"}. The key is hashed in PostgreSQL, rate-limited, and scoped to the account that created it.

Remote clients send .riv bytes to import_riv as dataBase64; export_riv returns dataBase64 when no local path is supplied. Remote MCP never accepts server filesystem paths. Cloud HTTP MCP is stateless by default, so requests can reach any application replica without sticky routing. Set OPENRIVE_MCP_STATELESS=false only for a self-hosted deployment that intentionally uses stateful sessions and has load-balancer affinity configured.

The local desktop app serves the same /api/mcp route on its loopback origin. Its bundled server has authentication off by default and is bound to 127.0.0.1; use the loopback URL shown by the desktop integration when configuring a local AI client.

Objects, timelines, states and properties can be referenced by name, so assistants don't need to track ids.

Assistants are told to use data binding properties rather than state machine inputs, which Rive deprecated: transitions read a property, listeners set one, and convert_inputs_to_data_binding migrates an older file. See data binding. get_project returns a compact outline of the file for the model to reason about.

• Name things ("a circle called Ball"). Later instructions can then refer to them.
• Ask for a state machine explicitly when you want interactivity ("add a hover input and listener").
• Ask it to "use theme colors" to get recolorable files.
• Review in the editor: every change is a normal edit, and you can keep refining by hand.

bun run test:mcp        # starts the server, creates a project, animates it and exports it

_{This page is generated from docs/mcp.md. Suggest an edit.}