API Reference

MotionLens MCP tools

MotionLens exposes its engine over the Model Context Protocol (MCP). Connect the server to Claude Code, Cursor, Windsurf, or any MCP client and your agent gets two tools. Each writes a Motion Blueprint + ready-to-paste code to disk and returns a summary, file paths, a code preview, and storyboard frames.

analyze_video

Analyze a local UI-animation clip (mp4 / mov / webm) on the user's machine.

pathstringrequired

Absolute path to the video file on disk.

frameworkenum

Target for the generated code — Framer Motion (default), CSS, GSAP, or Tailwind.

modeenum

Analysis depth — standard (default; Blueprint + callout storyboard) or precision (multi-pass, most accurate).

include_storyboardboolean

Return storyboard keyframe images. Default true.

save_dirstring

Directory to write the Blueprint + code into. Default ./motionlens-output.

analyze_url

Record a live website or app at a URL (headless browser) and analyze its motion. Best for auto-playing and scroll-triggered animation; tap-driven interactions should be recorded manually and passed to analyze_video.

urlstringrequired

The URL to record and analyze, e.g. https://linear.app.

interactionenum

load (default) records the page-load animation; scroll slowly scrolls top→bottom for scroll-triggered reveals.

viewportenum

desktop (1280×800, default) or mobile (390×844).

secondsnumber

Recording length. Default 10, clamped 3–30.

framework / mode / include_storyboard / save_dir—

Same as analyze_video.

Response

Both tools return the same shape:

{
  "summary": "one-sentence description of the motion",
  "blueprint_path": "./motionlens-output/blueprint.json",
  "code_path": "./motionlens-output/animation.tsx",
  "code_preview": "…first lines of the generated code…",
  "storyboard": ["frame-1.png", "frame-2.png", "frame-3.png"],
  "confidence": "high | medium | low"
}

The full Motion Blueprint (trigger, timeline, per-element motion, easing, stagger, feel, agent prompt) is written to blueprint_path so nothing truncates. See the Documentation for the Blueprint schema.

Auth & limits

The MCP server authenticates against your MotionLens account; each analysis consumes credits by mode (Standard 2 · Precision 3). Failed analyses are refunded automatically. Need higher throughput? Reach us at support@motionlens.dev.