Design Analysis MCP Server
Integrates with OpenAI's vision models to analyze design videos and images, extracting layout, typography, animations, and generating implementation specs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Design Analysis MCP Server analyze design from demo.mp4"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Design Analysis MCP Server
An MCP server that reverse-engineers design videos and images into structured frontend implementation specifications. Uses vision LLMs (OpenAI, Anthropic, Gemini) and FFMPEG for frame-level analysis.
Features
11 MCP tools organized into three tiers:
Tool | Purpose |
| Full orchestration — runs all layers + writes files |
| Grid, spacing, composition, hierarchy (no colors/animations) |
| Fonts, type scale, text animations (per-character, stagger) |
| Scroll segments, parallax, sticky detection (video only) |
| Multi-pass: burst-frame capture → find animations → crop + deep-dive |
| Single component with layout hypotheses + alternatives |
| "30-second test" — what makes this distinctive? |
| Side-by-side across layout, typography, animation, accessibility |
| Engineering-focused critique with actionable improvements |
| Complete spec: component tree, tokens, states, a11y |
| Catalog all visual assets (icons, gradients, palette) |
Related MCP server: figma-context-mcp-server
Architecture
┌─────────────┐
│ MCP Client │ (Claude Code, etc.)
└──────┬──────┘
│ stdio JSON-RPC
┌──────┴──────┐
│ index.ts │ Entry point, registers 11 tools
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
┌─────┴─────┐ ┌───┴───┐ ┌─────┴─────┐
│ Tools │ │Vision │ │Analyzers │
│ │ │Client │ │ │
│ analyze_* │ │ │ │ │ video_to_ │
│ reverse_* │ │ ├──Anthropic │ frames │
│ compare_* │ │ ├──OpenAI │ detect_ │
│ critique_ │ │ └──Gemini │ scroll_ │
│ generate_ │ │ │ segments │
│ extract_ │ │ │ images_ │
│ design_ │ │ │ to_pdf │
│ uniqueness│ │ │ analyze_* │
└───────────┘ └────────┘ └───────────┘Layered analysis
The orchestrator (analyze_design) runs layers independently to avoid mode confusion:
Layout — grid system, spacing principles, visual hierarchy
Typography — font categories, type scale, text animation details
Scroll — PSNR-based pixel-shift detection between frames
Motion — multi-pass: find animations → crop region → deep-dive
Uniqueness — "30-second test": what would a designer remember?
Confidence scoring
Every estimate includes confidence: number (0–1) and alternatives: string[] so downstream LLMs can distinguish reliable findings from speculation. Estimates describing what the model can see (movement direction, opacity change) get higher confidence than inferred values (exact CSS properties, easing curves, font names).
Multi-pass animation analysis
Burst capture — 15 FPS for first 3 seconds (captures fast discrete animations like slot-machine effects at 400–800ms)
Pass 1 — find all animations + estimate screen regions
Pass 2 — crop each region and deep-dive with a focused prompt
File-based output
analyze_design writes results to analysis/{name}/:
File | Contents |
| Most memorable elements, confidence report |
| Grid, spacing, composition |
| Fonts, type scale, text animations |
| Animation details |
| Design uniqueness output |
| Design tokens, component specs |
Setup
Prerequisites
Node.js 22+
FFMPEG (for video frame extraction, scroll detection)
At least one API key: OpenAI, Anthropic, or Gemini
Install
git clone <repo>
cd design-analysis-mcp-server
npm installConfigure
Copy .env.example to .env and set at least one API key:
cp .env.example .env
# Edit .env with your API keysOptionally edit config.yaml to change model priority, frame extraction settings, or output directories.
Build
npm run buildAdd to Claude Code
In your ~/.opencode.jsonc:
{
"mcpServers": {
"design-analysis": {
"command": "node",
"args": ["/path/to/design-analysis-mcp-server/build/index.js"],
"env": {
"OPENAI_API_KEY": "sk-...",
"ANTHROPIC_API_KEY": "sk-ant-...",
"GEMINI_API_KEY": "AIza..."
}
}
}
}Usage Examples
# Full analysis of a design video
analyze_design path=/path/to/demo.mp4 name=demo-v1
# Analyze only layout
analyze_layout path=/path/to/screenshot.png
# Reverse-engineer a specific component
reverse_engineer_component path=/path/to/screen.mp4 element_description="hero section with CTA button"
# Multi-pass animation deep-dive
reverse_engineer_animation path=/path/to/demo.mp4 region={x:100,y:200,width:300,height:400}
# Compare two designs
compare_designs referenceA={path:/path/to/v1.mp4,type:video} referenceB={path:/path/to/v2.mp4,type:video}
# Generate implementation spec
generate_implementation_spec path=/path/to/demo.mp4
# 30-second test for design uniqueness
design_uniqueness path=/path/to/demo.mp4Configuration Reference
Config key | Default | Description |
|
| Model priority list; fallback on error |
|
| Standard mode frame interval |
|
| PNG quality (2–31, lower = better) |
|
| PSNR threshold for scene detection |
|
| Max frames in any extraction mode |
|
| Max pages in generated PDFs |
|
| Frames to merge when detecting scroll |
Prompt Philosophy
All analyzer prompts follow a principle-first structure:
What principle does this follow? (high confidence — directly observable)
What mechanism could produce this? (medium confidence — alternatives listed)
What are the estimated values? (low confidence — clearly labeled)
Prompts instruct models to say "uncertain" rather than guess wrong, and to list alternative mechanisms when confidence < 0.8.
Available Tools
11 toolsanalyze_designA
Full design analysis orchestrator. Runs ALL layers (layout, typography, scroll, motion) and aggregates results. For focused analysis, use layer-specific tools.
Inputs: reference (required).
analyze_layoutA
Layer 1: Analyze ONLY layout, spacing, composition, and hierarchy. Ignores animation, typography, and colors. Returns grid system, regions, spacing patterns, alignment, and visual hierarchy.
Inputs: reference (required).
analyze_scrollA
Layer 3: Analyze scroll behavior from a video recording. Detects scroll segments, pixel shifts, parallax, and sticky elements. Requires a video of scrolling interaction.
Inputs: reference (required).
analyze_typographyA
Layer 2: Analyze ONLY typography, including text animations (per-character, per-word, stagger, easing). Describes fonts, type scale, line breaks, weights, and how every text element animates.
Inputs: reference (required).
compare_designsA
Compare two designs (videos or images) side by side. Returns layout, typography, color, component, animation, and accessibility differences with implementation complexity assessment.
Inputs: referenceA (required), referenceB (required).
critique_designC
Engineering-focused design critique. Evaluates layout, typography, color, animation, accessibility, and implementation complexity with specific actionable feedback.
Inputs: reference (required).
design_uniquenessA
Analyze what makes a design DISTINCTIVE and MEMORABLE. The '30-second test': if a designer watched this for 30 seconds, what 5 ideas would they remember 3 days later? Identifies the single most recognizable animation, interaction philosophy, top ideas worth borrowing, and things to avoid copying. Ignores layout/colors/typography specifics — focuses purely on interaction uniqueness.
Inputs: reference (required).
extract_assetsA
Extract every visual asset from a design: icons, illustrations, photos, logos, gradients, patterns. Returns a catalog with type, name, description, suggested format (SVG/PNG/CSS), and the full color palette.
Inputs: reference (required).
generate_implementation_specA
Generate a complete frontend implementation specification. Includes component tree, exact design tokens (colors, typography, spacing), component states, animation specs, and accessibility requirements — enough for an engineer to implement without ever seeing the original design.
Inputs: reference (required).
reverse_engineer_animationA
Reverse-engineer every animation in a video with multi-pass analysis. Pass 1: extract high-FPS frames and find all animations. Pass 2: crop each animation region and deep-dive into timing, easing, stagger, per-character details, and implementation suggestions. Optionally provide a specific region to skip Pass 1 and analyze a single element.
Inputs: reference (required), region, element.
reverse_engineer_componentA
Reverse-engineer a single component from a design. Optionally specify a screen region to crop + zoom for focused analysis. Returns HTML structure, CSS layout, styling details, all states (hover/active/focus/disabled), and accessibility requirements.
Inputs: reference (required), region, element_description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a specific aspect of design analysis (layout, typography, scroll, animation) or a distinct task (comparison, critique, uniqueness, asset extraction, spec generation, reverse engineering). The orchestrator tool explicitly directs users to layer-specific tools for focused analysis, eliminating ambiguity.
Most tools follow a verb_noun pattern (analyze_*, compare_designs, critique_design, extract_assets, generate_implementation_spec, reverse_engineer_*). However, 'design_uniqueness' deviates by omitting a verb (e.g., 'analyze_uniqueness'), making it slightly less consistent.
With 11 tools, the server covers all major aspects of design analysis (layout, typography, scroll, motion, comparison, critique, uniqueness, assets, specification, reverse engineering) without being bloated. Each tool serves a clear purpose within the domain.
The tool surface covers core analysis layers, comparison, critique, uniqueness, asset extraction, spec generation, and reverse engineering. A minor gap is lack of a dedicated color analysis tool, but colors are handled within extract_assets, critique, and compare tools, so it's not critical.
Maintenance
Related MCP Connectors
FFmpeg as a service for AI agents: typed video editing tools, async jobs, downloadable outputs.
UI design from prompts, screenshots, and URLs for AI coding agents and theme tokens.
Transform video, audio and images, and generate media from prompts. FFmpeg, captions, models.
Turn screen recordings and video links into change lists with screenshots an AI can act on.
Related MCP Servers
- AlicenseAqualityDmaintenanceConverts Figma designs into structured code context with token-aware styling, enabling AI agents to generate production-level frontend code.111 npmMIT
- FlicenseAqualityDmaintenanceConverts Figma design data into structured semantic analysis JSON and screenshots for AI agents to use in design-to-code workflows.5-
- AlicenseAqualityBmaintenanceProvides image and video analysis capabilities for LLMs, with local preprocessing (ffmpeg/OpenCV) and any OpenAI-compatible vision model for understanding and Q&A.4MIT
- AlicenseNot gradedqualityCmaintenanceConverts any rendered web page into a complete, LLM-readable design specification—including block screenshots, distilled computed CSS, design tokens, responsive deltas, and alpha-channel-analyzed assets—so models can accurately reproduce the design.MIT