figma-spec-mcp

<p align="center"> <img src="assets/banner.png" alt="figma-spec-mcp — Bridge Figma to Game Engines" width="720" /> </p>

Bridge Figma to any platform — Unity UGUI mappings built-in, structured output for React, Flutter, SwiftUI, and more. Layout audit, design tokens, accessibility checks, prototype flows, version diffs, and platform-ready specs — all through MCP.

Works with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, VS Code + Copilot, Windsurf, Cline, Continue.dev, Zed.

Security note: Your Figma access token is passed as a tool argument. Never commit it to version control. Use environment variables or your AI client's secret management to supply it at runtime.

---

Platform Support

Platform	What you get
Unity	map_to_unity — RectTransform data, layout groups, anchoring, UGUI component mapping
React	map_to_react — JSX tree, Tailwind/CSS classes, shadcn/MUI/Chakra/Radix component mapping, TypeScript props
React Native	map_to_react_native — View/Text/TouchableOpacity, StyleSheet, React Native Paper/NativeBase mapping
Flutter	map_to_flutter — Widget tree, Material/Cupertino components, ThemeData extraction
SwiftUI	map_to_swiftui — VStack/HStack/ZStack, modifier chains, Color asset extraction
Tailwind CSS	extract_design_tokens → Tailwind config export
Any platform	generate_implementation_contract → structured spec with scope, assets, states, and acceptance criteria

Your AI agent reads the structured output and generates platform-specific code. No manual translation needed.

---

Quick Start

1. Get a Figma access token → figma.com/developers/api#access-tokens

2. Add to your MCP config (Claude Desktop, Cursor, VS Code, or any MCP client):

{
  "mcpServers": {
    "figma-spec-mcp": {
      "command": "npx",
      "args": ["-y", "figma-spec-mcp@beta"]
    }
  }
}

3. Restart your AI client and use the tools.

Your file key is in the Figma URL: figma.com/file/<FILE_KEY>/...

---

Why figma-spec-mcp?

Most Figma MCP tools forward raw API responses. figma-spec-mcp adds stable envelopes, focused derivations, and reusable engineering outputs:

• Deterministic JSON responses with a shared response envelope
• Built-in disk cache with freshness metadata on every result
• Source traceability for tokens, mappings, and extracted relationships
• Platform-ready outputs for Unity, codebase mapping, and image export workflows

---

Tools

• inspect_layout — Inspects a Figma frame and returns hierarchy, layout structure, spacing, constraints, annotations, and basic accessibility warnings.
• extract_design_tokens — Extracts color, typography, and spacing tokens from a Figma file and exports them as CSS variables, Style Dictionary JSON, or Tailwind config.
• map_to_react — Maps a Figma frame to a React component tree with Tailwind/CSS classes, component library suggestions (shadcn, MUI, Chakra, Radix), asset hints, and TypeScript prop interfaces from variants.
• map_to_react_native — Maps a Figma frame to React Native components (View, Text, TouchableOpacity, TextInput) with StyleSheet output and React Native Paper/NativeBase library mapping.
• map_to_flutter — Maps a Figma frame to a Flutter Widget tree (Container, Column, Row, Stack) with Material/Cupertino component mapping and ThemeData extraction.
• map_to_swiftui — Maps a Figma frame to SwiftUI views (VStack, HStack, ZStack) with modifier chains and Color asset extraction.
• map_to_unity — Produces a Unity UGUI-oriented mapping with RectTransform data, layout groups, suggested components, notes, and warnings.
• resolve_components — Resolves instance nodes to their backing component definitions and returns source file and source node references.
• extract_flows — Extracts prototype transitions from a page or frame and returns directed flow connections plus a deterministic frame order.
• bridge_to_codebase — Scans a local project and maps Figma component names to likely implementation files using filename heuristics.
• diff_versions — Compares two Figma file versions and reports added, removed, and modified nodes.
• extract_variants — Reads a component set and returns structured variant metadata, parsed properties, dimensions, layout details, fills, and typography.
• export_images — Exports one or more Figma nodes as PNG, JPG, SVG, or PDF and returns the image URLs.
• audit_accessibility — Audits a frame for accessibility issues such as contrast, touch targets, font size, missing alt text, and color-only distinctions.
• simplify_context — Produces a token-efficient, LLM-oriented summary tree by collapsing wrappers, grouping repeated nodes, and truncating deep hierarchies.
• lint_handoff_readiness — Audits a frame for engineering handoff readiness: unnamed layers, absolute positioning soup, missing auto-layout, orphaned nodes, oversized images.
• generate_implementation_contract — Produces a structured implementation spec with scope, assets, states, interactions, dependencies, typography, colors, and acceptance criteria.
• extract_missing_states — Scans components for missing UI states (hover, pressed, disabled, loading, error, empty) against a standard expected-state set.
• flow_to_test_cases — Converts prototype flows into QA-ready test cases with navigation steps, expected outcomes, and flow coverage gaps.

---

Features

v0.1 — Core

• inspect_layout, extract_design_tokens, map_to_unity
• Disk cache with SHA-256 keying and 1h TTL

v0.2 — Intelligence

• Token name preservation from Figma styles
• Depth-limited chunking for large files
• Mixed/rich text runs extraction
• Annotation extraction, framework-aware hints (Unity, React, SwiftUI, Web)

v0.3 — Workflows

• resolve_components — multi-file component traversal
• extract_flows — prototype flow graph
• bridge_to_codebase — Figma → repo file matching
• diff_versions — structured version diff
• extract_variants — component set batch extraction

v0.4 — Quality & DX

• export_images — PNG/JPG/SVG/PDF export
• audit_accessibility — WCAG 2.1 contrast, touch targets, font size
• simplify_context — AI-optimized, token-efficient output
• Tool registry pattern for easy contribution
• Rate limit handling (429 + Retry-After)

v0.5 — Handoff & QA

• lint_handoff_readiness — design-to-code readiness audit with scoring
• generate_implementation_contract — structured implementation scope + acceptance criteria
• extract_missing_states — component state coverage analysis
• flow_to_test_cases — prototype flows → QA test scenarios

v0.6 — Multi-Platform Mappers

• map_to_react — Figma → React with Tailwind/CSS, shadcn/MUI/Chakra/Radix, TypeScript props
• map_to_react_native — Figma → React Native with StyleSheet, Paper/NativeBase component mapping
• map_to_flutter — Figma → Flutter Widget tree with Material/Cupertino, ThemeData extraction
• map_to_swiftui — Figma → SwiftUI with modifier chains, Color asset extraction
• Normalized UI AST foundation — shared platform-agnostic tree powering all 4 platform mappers

---

Response Shape

All 19 tools return a consistent top-level envelope:

{
  "schema_version": "0.1.0",
  "source": { "file_key": "abc123", "node_id": "1:23" },
  "freshness": {
    "fresh": true,
    "timestamp": "2026-03-26T10:00:00.000Z",
    "ttl_ms": 3600000
  },
  "warnings": [],
  "data": {}
}

Tool-specific results live in data, and most tools also include low-level cache metadata there.

---

Caching

Responses are cached to disk (default: $TMPDIR/figma-spec-mcp-cache/) by file key and request shape with a 1-hour TTL. Cache metadata is included in responses:

"cache": {
  "cachedAt": "2026-03-26T10:00:00.000Z",
  "expiresAt": "2026-03-26T11:00:00.000Z",
  "fileVersion": "123456789",
  "fresh": true
}

---

Development

git clone https://github.com/zaferdace/figma-spec-mcp
cd figma-spec-mcp
npm install
npm run build
node dist/index.js

---

Roadmap

• [x] map_to_react — React component tree with Tailwind/CSS, component library mapping, TypeScript props
• [x] map_to_react_native — React Native with StyleSheet, Paper/NativeBase mapping
• [x] map_to_flutter — Flutter Widget tree with Material/Cupertino, ThemeData
• [x] map_to_swiftui — SwiftUI views with modifier chains, Color assets
• [ ] detect_design_drift — Compare Figma design against codebase implementation
• [ ] map_to_unreal_umg — Unreal Engine UMG widget mapping
• [ ] map_to_godot_control — Godot Control node mapping
• [ ] Webhook-triggered spec generation

---

License

MIT © Zafer Dace