Motion.page MCP Server

MCP server that enables AI agents to create and manipulate animations in the Motion.page Builder. Supports 15 tools across 3 tiers — from one-call animation creation to surgical property edits.

Quick Start

Claude Code (Auto Setup)

claude mcp add motionpage-desktop-mcp -- npx @motion.page/desktop-mcp

Then ask Claude to create an animation:

Create a fade-in animation for .hero-title on page load

Cursor / Windsurf / Other Agents

Add to your MCP config file (.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, etc.):

{
  "mcpServers": {
    "motionpage-desktop-mcp": {
      "command": "npx",
      "args": ["@motion.page/desktop-mcp"]
    }
  }
}

What Agents Can Do

The golden path — create a complete animation in one call:

create_timeline({
  name: "Hero Entrance",
  trigger: { type: "pageLoad" },
  animations: [{
    selector: ".hero-title",
    from: { opacity: 0, y: 50 },
    to: { opacity: 1, y: 0 },
    duration: 0.8,
    ease: "power3.out"
  }]
})

Then add more elements, fine-tune properties, and preview the output:

add_animation({ selector: ".subtitle", from: { opacity: 0 }, duration: 0.6 })
update_animation({ nodeUid: "abc", ease: "elastic.out" })
preview_code()

Tools (15 total)

Tier 1 — High-Level (80% of use cases)

| Tool | Description | |------|-------------| | create_timeline | Create a timeline with name, trigger, and animations in one call | | add_animation | Add an element with animation atomically (no broken states) | | update_animation | Update from/to/duration/ease/stagger/split on an existing node | | set_trigger | Set trigger type and options (pageLoad, scroll, hover, click, etc.) |

Tier 2 — Fine-Tuning

| Tool | Description | |------|-------------| | set_property | Set a single animation property with full store-level control | | remove_property | Remove a property (reverts to element's natural CSS state) |

Tier 3 — Introspection

| Tool | Description | |------|-------------| | list_triggers | All 8 trigger types with descriptions and examples | | list_properties | All animatable properties by category | | list_easings | All easing functions with recommendations | | get_builder_state | Current timeline state (or guidance when empty) | | create_timeline | Create new animation timeline | | list_timelines | List all timelines in a project | | load_timeline | Load a timeline for editing | | get_timeline | Read-only timeline details | | delete_timeline | Permanently delete a timeline | | preview_code | Generate SDK code without saving |

Simplified Input Format

Tier 1 tools accept clean property values. The server handles unit conversion automatically:

{ opacity: 0, y: 50 }         → y uses default unit (%)
{ x: "100px" }                 → explicit unit from CSS string
{ scale: 0.8 }                 → no unit needed
{ filter: "blur(10px)" }       → parsed into builder filter array

Supported Triggers

pageLoad (default), pageExit, scroll, hover, click, mouseMove, gesture, cursor

Supported Animation Properties

Transform: x, y, z, scale, scaleX, scaleY, rotate, rotateX, rotateY, skewX, skewY, transformOrigin Appearance: opacity, backgroundColor, color, borderColor Dimensions: width, height Filter: CSS filter string (e.g., "blur(10px) grayscale(50%)") Background: backgroundPosition Features: stagger, split text (chars/words/lines), mask, fit, repeat

Recommended Easings

• power2.out — subtle, professional
• power3.out — punchy entrances
• back.out — playful overshoot
• elastic.out — spring effect
• bounce.out — bouncy landing

Architecture

packages/mcp-server/
├── bin/mcp-server.ts          # CLI entry point (stdio)
├── src/
│   ├── server.ts              # MCP server factory (15 tools registered)
│   ├── state/
│   │   ├── HeadlessStore.ts   # Headless state manager (Immer, no React)
│   │   └── normalizer.ts      # Simplified input ↔ store format conversion
│   ├── tools/
│   │   ├── introspection.ts   # list_triggers, list_properties, list_easings, get_builder_state
│   │   ├── timeline.ts        # create_timeline, add_animation, CRUD tools
│   │   ├── animation.ts       # update_animation, set_property, remove_property
│   │   ├── trigger.ts         # set_trigger with SDK→builder name mapping
│   │   └── codegen.ts         # preview_code
│   ├── types/                 # Response contract, trigger/property/easing reference data
│   └── transports/stdio.ts    # stdio transport
├── llms.txt                   # Agent-readable reference
└── package.json

Connection Modes

Desktop Mode (live connection, real persistence)

When the Motion.page Desktop app is running, the MCP server connects to it automatically via a local WebSocket bridge. Timelines are persisted to Convex. The agent sees "Connected to Motion.page Desktop" on first get_builder_state call.

No extra configuration required — just open the Desktop app before starting your AI agent session.

Disconnected Mode (in-memory, no persistence)

When the Desktop app is not running, the server operates without a platform connection. Introspection tools and in-memory editing work immediately. Timeline CRUD tools return guidance to open the Desktop app.

Development

# Run tests
bun test packages/mcp-server

# Type check
cd packages/mcp-server && bun run typecheck

# Start server locally (stdio)
node_modules/.bin/tsx packages/mcp-server/bin/mcp-server.ts

Related

• packages/claude-plugin — SDK skills plugin for Claude Code (teaches agents to write @motion.page/sdk code)
• packages/sdk — The Motion.page animation SDK
• docs/specs/mcp-server.md — Full implementation spec

License

FSL-1.1-Apache-2.0 — Functional Source License