Motionlint

What bobaba99/motionlint does

The bobaba99/motionlint MCP server brings MotionLint's browser-based motion inspection into an MCP workflow for AI coding agents. It evaluates a running web page rather than inferring behavior from JSX, HTML, or CSS alone. The deterministic audit checks 13 animation quality rules, including duration, easing curves, stagger intervals, exit timing, reduced-motion handling, and hover behavior that may be inappropriate for touch devices.

The audit reports measured values and suggested fixes. It does not require an API key and can run against a local development server, staging deployment, or another reachable URL. MotionLint also provides optional design review using a vision-capable model. That review can inspect screenshots at multiple viewports and short frame sequences from real user journeys, then return ranked findings.

How it works

MotionLint uses Playwright and Chromium to load the target page and observe its actual behavior. Install Chromium once with npx playwright install chromium; the project requires Node 18 or newer. Deterministic checks run locally and offline.

For model-assisted review, MotionLint captures page screenshots or 50-millisecond animation frame bursts. The frames can be assembled into contact sheets for analysis. Providers can be selected explicitly, or MotionLint can detect a reachable Ollama service, Anthropic key, OpenAI key, or Google key. With no provider available, the pipeline can use a deterministic mock provider for smoke testing.

The bobaba99/motionlint MCP server is started as a stdio process with npx -y motionlint mcp, allowing an MCP client to invoke the package from an agent session.

Setup and configuration

Install the browser dependency first:

npx playwright install chromium

Register the server with an MCP-compatible client using:

claude mcp add motionlint -- npx -y motionlint mcp

No API key is needed for the deterministic audit. Vision review can use ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY, or a local Ollama instance at its automatically detected address. MotionLint loads these values from a .env file in the working directory, while real environment variables take precedence. Provider and model selection are also available through command-line options.

Tools and capabilities

The bobaba99/motionlint MCP server provides access to MotionLint workflows including:

• Auditing a URL against deterministic animation standards.
• Reviewing a page across multiple viewports and UX dimensions.
• Reviewing scripted journeys with captured animation frames.
• Tuning page animations through an interactive HTML interface.
• Discovering routes from a sitemap or Next.js app directory.
• Reviewing Storybook stories through their iframe routes.
• Checking light, dark, and forced-colors modes.
• Producing HTML or SARIF reports for sharing and CI code-scanning workflows.
• Comparing a preview URL with a production baseline.

The command-line package also supports interaction state grids, finding limits, and provider evaluation. These options may be useful when an agent needs focused findings or CI output rather than a full report.

Limitations and notes

The deterministic checks only evaluate behavior that can be observed on the loaded page. The target must be reachable by the browser, and Chromium must be installed locally. Model-assisted review requires a configured provider unless the mock provider is sufficient for a smoke test; provider output is therefore separate from the offline audit.

The README specifically documents use with Claude Code and Cursor. Reports, screenshots, videos, and flow artifacts are written under .motionlint/ paths when using the corresponding MotionLint workflows. The project is released under the MIT license.