Figma AI Context

An MCP server that transforms Figma API data into AI-friendly formats, optimized for LLM code generation workflows.

Features

• Condensed Text Format — 60%+ token savings over JSON, ideal for LLM context windows
• One-shot Codegen — Structure + design tokens + component definitions + color/font specs in a single call
• CSS / Tailwind Output — Generate style code directly, with recursive component tree support
• SVG Export — Detect icons/vectors and export as SVG files
• Node Search — Find nodes by name/type quickly, even in large files
• Node Diff — Compare two nodes or track changes to the same node over time via version history
• Component Variants — Extract all property combinations from component sets for Props interfaces
• Style System — Retrieve color/text/effect style definitions from files
• Semantic Role Inference — Auto-detect 28 UI semantic roles (BUTTON, CARD, ICON, etc.)
• Smart Token Budget — Auto-control output size; gracefully reduce depth when over budget
• Resilient Requests — Auto-retry, concurrency control, LRU cache for stability

Installation

Option 1: npx (Recommended)

No installation needed — use directly in your MCP client config:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ai-context"],
      "env": {
        "FIGMA_TOKEN": "figd_your_token"
      }
    }
  }
}

Option 2: Global Install

npm install -g figma-ai-context

{
  "mcpServers": {
    "figma": {
      "command": "figma-ai-context",
      "env": {
        "FIGMA_TOKEN": "figd_your_token"
      }
    }
  }
}

Option 3: From Source

git clone https://github.com/xiehuan123/figma-ai-context.git
cd figma-ai-context
npm install
npm run build

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/path/to/figma-ai-context/dist/index.js"],
      "env": {
        "FIGMA_TOKEN": "figd_your_token"
      }
    }
  }
}

Client Config Locations

| Client | Config Path | |--------|-------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Claude Code | mcpServers field in .claude/settings.json | | Cursor | Settings → MCP → Add Server | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | VS Code (Copilot) | .vscode/mcp.json |

Getting a Figma Token

1. Log in to Figma
2. Go to Settings → Personal Access Tokens
3. Create a new token and copy the string starting with figd_

Available Tools

| Tool | Description | |------|-------------| | get_file_structure | Get page and top-level frame structure overview | | get_node | Get AI-friendly node data (JSON / condensed / condensed-v2 text) | | get_page_for_codegen | One-shot fetch of full codegen context | | get_node_css | Convert node to CSS or Tailwind classes | | get_texts | Extract all text content, supports Figma URL input | | search_nodes | Search nodes by name/type for quick location | | get_styles | Get color/text/effect/grid style definitions | | get_components | List all components in a file | | get_component_variants | Get all variant property combinations | | get_variables | Get Design Variables / Tokens | | get_images | Get image export URLs (PNG/SVG/PDF) | | export_svg | Export nodes as SVG and save to temp directory | | get_icons_index | Get summary index of exported SVGs in session | | diff_nodes | Compare two nodes or track node changes over time | | get_versions | List file version history for diff operations |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | FIGMA_TOKEN | Yes | Figma Personal Access Token | | FIGMA_CACHE_TTL | No | Cache TTL in milliseconds (default: 60000) | | FIGMA_DEBUG | No | Enable verbose API request logs when set to 1, true, yes, or on. get_node artifacts are always written to the configured .figma-temp/raw, .figma-temp/optimized, .figma-temp/condensed, and .figma-temp/condensed-v2 directories | | FIGMA_TEMP_DIR | No | Override the temp artifact directory. By default artifacts are written under the runtime module directory, such as dist/.figma-temp for a local build |

Data Processing

| Processing | Description | |------------|-------------| | Noise removal | Strip pluginData, exportSettings, invisible nodes | | Color flattening | RGBA objects → #hex or rgba() | | Layout semantics | Auto Layout → flex-row/flex-col, start/center/end | | Layout inference | Non-auto-layout frames can be marked as inferred-row, inferred-col, or inferred-grid from child bounds | | Padding compression | Collapse identical sides to single value | | Depth control | Configurable recursion depth + token budget auto-truncation | | Caching | LRU cache (max 50 entries), configurable TTL | | Resilience | Auto-retry 429/5xx (exponential backoff), concurrency limit (max 5) | | Debug output | get_node stores raw, optimized, and condensed artifacts under the configured temp directory; FIGMA_DEBUG=1 additionally stores verbose API logs |

Layout Semantics

Figma Auto Layout is preserved as the authoritative layout signal:

• layoutMode: "HORIZONTAL" becomes layout.mode: "row" in optimized JSON and flex-row in condensed text.
• layoutMode: "VERTICAL" becomes layout.mode: "col" in optimized JSON and flex-col in condensed text.

When a node has no Auto Layout, or when Figma returns layoutMode: "NONE", the transformer may infer a lightweight layout hint from visible child bounding boxes:

[FRAME "Manual Row" 460x32 inferred-row inferred-gap:16 confidence:high]

In optimized JSON this appears as:

{
  "inferredLayout": {
    "mode": "row",
    "confidence": "high",
    "source": "bounds",
    "gap": 16
  }
}

The inferred marker is intentionally separate from layout / flex-row / flex-col, so it does not override real Figma Auto Layout.

Condensed Icon References

get_node(format: "condensed") marks likely icons directly in the compressed tree. When SVG preview/export succeeds, the same line also includes the concrete SVG file reference:

[BASICS_SETTINGS "Basics/settings" 24x24 icon svg:"icon-Basics-settings_2-1.svg" svgPath:"E:/project/.figma-temp/svg/icon-Basics-settings_2-1.svg"]

This lets an AI client see where the icon appears in the hierarchy and which local SVG file to read without making a second discovery request. If an icon is detected but SVG export is unavailable, the line still includes icon without svgPath.

Condensed V2

get_node defaults to format: "condensed-v2" because this is the recommended format for AI code generation. It keeps the tree readable while extracting repeated noise into shared dictionaries:

@format condensed-v2
@assets
svgBase:"C:/project/.figma-temp/svg/"

@colors
c1=#191919
c2=#eceeed

@sizes
z1=24x24
z2=534x296

@styles
s1=bg:c1 radius:20 flex-col gap:16 p:24

@tree
[FRAME "CPU" size:z2 @s1]
  [MODULE_CPU "Module/CPU" size:z1 icon:i1]
  [TEXT "Title" font:16/400 text:c2 "Intel Core i9"]

Use this format when feeding data directly to an AI coding agent. It avoids repeating long svgPath values, repeated sizes, gradients, colors, effects, and common layout tokens on every node.

condensed-v2 can also add conservative overlay hints for decorative layers such as glow/blur nodes:

[FRAME "Progress Row" has-overlay flex-row]
  [FRAME "发光" size:z1 overlay:next layer:decor]
  [FRAME "Frame 1" size:z1 layer:content]

[FRAME "Card" has-overlay flex-col]
  [ELLIPSE "Ellipse 1" 168x168 overlay:parent layer:decor pos:absolute]
  [FRAME "Title" 486x24]

The tree order is preserved. overlay:next tells AI clients that the decorative node should visually sit behind the next sibling. overlay:parent marks background decoration inside the parent, such as a large blurred ellipse. Nodes with Figma layoutPositioning: "ABSOLUTE" include pos:absolute, meaning they are outside the parent layout flow.

Debug Web

For local inspection, run:

npm run debug:web

Then open the printed local URL, usually http://127.0.0.1:3333.

The debug page can:

• accept a Figma token and URL / fileKey / nodeId
• show raw API data, optimized JSON, and AI-friendly condensed text
• preview detected icons as SVG files under .figma-temp/svg
• download the generated SVG previews as a zip from /api/icons.zip

The checkbox on the page is Preview icons: it generates local SVG previews. Actual export/download is done by the Download icon package button.

Temp Artifacts

Runtime files are stored under the runtime module directory by default. For a local build that means dist/.figma-temp. Set FIGMA_TEMP_DIR to make MCP and debug web share a fixed artifact directory.

The MCP server clears and recreates the configured temp directory on startup. The debug web server only ensures the directory structure exists, so starting npm run debug:web does not erase existing artifacts.

Artifact write paths recreate missing temp directories before writing, so deleting .figma-temp while the MCP server is running no longer breaks the next get_node artifact write.

get_node(format: "json") returns an artifacts object with tempDir, rawPath, optimizedPath, condensedPath, and condensedV2Path, so AI clients should read those explicit paths instead of guessing filenames.

| Path | Written by | Purpose | |------|------------|---------| | .figma-temp/raw | get_node, debug web inspect | Raw Figma node/API payload snapshots | | .figma-temp/optimized | get_node, debug web inspect | Simplified tree, summary, variables, condensed data | | .figma-temp/condensed | get_node, debug web inspect | Legacy condensed text files | | .figma-temp/condensed-v2 | get_node, debug web inspect | Default condensed-v2 text files for AI code generation | | .figma-temp/svg | SVG preview/export paths | Downloaded SVG files | | .figma-temp/icons/index.json | SVG preview/export paths | Current session icon index | | .figma-temp/logs | FIGMA_DEBUG=1 only | Verbose Figma API request/response logs |

Package Contents

The npm package ships compiled dist/*.js, dist/*.d.ts, and source map files, plus debug-web/index.html, doc/, and README.md. Runtime .figma-temp artifacts are excluded from the package and repository history.

See doc/debug-and-icons.md for the full debug and icon workflow.

Project Structure

src/
  index.ts          # MCP Server entry, tool registration
  figma-client.ts   # Figma REST API client (retry + cache + concurrency)
  transformer.ts    # Data transform (simplify, compress, semantic inference)
  helpers.ts        # URL parsing, text extraction, CSS/Tailwind gen, node search
  diff.ts           # Node diff logic
  svg-exporter.ts   # SVG detection and export
  temp-manager.ts   # Temp directory lifecycle management
  logger.ts         # Logging system

Development

npm run build      # Compile
npm run dev        # Watch mode
npm test           # Run tests
npm run test:watch # Watch mode tests

Publishing

Automated via GitHub Actions. Triggered on Release creation:

1. Bump version: npm version patch (or minor / major)
2. Push tag: git push origin master --tags
3. Create a Release on GitHub targeting the tag
4. CI builds and publishes to npm and GitHub Packages

Requirements

• Node.js 18+ (native fetch required)
• Figma Personal Access Token

中文说明

将 Figma API 数据转换为 AI 友好格式的 MCP 服务器，专为 LLM 代码生成场景优化。

主要特性

• 压缩文本格式 — 比 JSON 节省 60%+ token，适合 LLM 上下文
• 一站式代码生成 — 结构 + design tokens + 组件定义 + 颜色/字体规范一次获取
• CSS / Tailwind 输出 — 直接生成样式代码，支持递归组件树
• SVG 导出 — 检测图标/矢量图形，导出为 SVG 并保存
• 节点搜索 — 按名称/类型快速定位节点
• 节点对比 — 对比两个节点差异或通过版本历史追踪同一节点的变化
• 组件 Variants — 提取组件集的所有属性组合，直接生成 Props 接口
• 样式系统 — 获取文件的颜色/文字/效果样式定义
• 语义角色推断 — 自动识别 28 种 UI 语义角色（BUTTON, CARD, ICON 等）
• 智能预算控制 — token 预算自动控制输出大小，超预算时智能降低深度
• 请求容错 — 自动重试、并发控制、LRU 缓存，稳定不崩溃

快速开始

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ai-context"],
      "env": {
        "FIGMA_TOKEN": "figd_你的token"
      }
    }
  }
}

详细安装方式和工具列表请参考上方英文文档。

License

MIT