Figma Context MCP

MCP server for seamless Figma design integration with AI coding tools

Features • Quick Start • MCP Capabilities • Architecture • Documentation • 中文文档

What is This?

Figma Context MCP is a Model Context Protocol (MCP) server that bridges Figma designs with AI coding assistants like Cursor, Windsurf, and Cline.

When AI tools can access Figma design data directly, they generate more accurate code on the first try—far better than using screenshots.

Note: This project is based on Figma-Context-MCP, with optimized data structures and intelligent layout detection algorithms.

Features

Core Capabilities

Capability	Description
Smart Layout Detection	Automatically infers Flexbox/Grid layouts from absolute positioning
Icon Merging	Intelligently merges vector layers into single exportable icons
CSS Generation	Converts Figma styles to clean, usable CSS
Image Export	Downloads images and icons with proper naming
Multi-layer Caching	L1 memory + L2 disk cache to reduce API calls
Design-to-Code Prompts	Built-in professional prompt templates to guide AI code generation
Lightweight Resource Access	Resources API provides low-token data access

Key Improvements

Feature	Before	After
Icon exports	~45 fragmented	2 merged (96% reduction)
Layout detection	Manual absolute	Auto Flexbox/Grid inference
CSS output	Raw values	Optimized with defaults removed
API calls	Every request	24-hour smart caching

Quick Start

Prerequisites

Node.js >= 18.0.0
A Figma account with API access

Installation

Via Smithery (Recommended)

npx -y @smithery/cli install @1yhy/Figma-Context-MCP --client claude

Via npm

npm install -g @yhy2001/figma-mcp-server

From Source

git clone https://github.com/1yhy/Figma-Context-MCP.git
cd Figma-Context-MCP
pnpm install
pnpm build

Configuration

1. Get Figma API Token

Go to Figma Account Settings
Scroll to "Personal access tokens"
Click "Create new token"
Copy the token

2. Configure Your AI Tool

Cursor / Windsurf / Cline

Add to your MCP configuration file:

{
  "mcpServers": {
    "Figma": {
      "command": "npx",
      "args": ["-y", "@yhy2001/figma-mcp-server", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "your-figma-api-key"
      }
    }
  }
}

HTTP/SSE Mode (Local Development)

# From source (development)
cp .env.example .env  # Add FIGMA_API_KEY to .env
pnpm install && pnpm build
pnpm start            # Starts on port 3333

# Or with environment variable
FIGMA_API_KEY=<your-key> pnpm start

# Or via global install
figma-mcp --figma-api-key=<your-key> --port=3333

# Connect via SSE
# URL: http://localhost:3333/sse

Usage Example

Please implement this Figma design: https://www.figma.com/design/abc123/MyDesign?node-id=1:234

Use React and Tailwind CSS.

MCP Capabilities

This server provides full MCP capabilities support:

┌─────────────────────────────────────────────────────────────┐
│                  Figma MCP Server v1.1.0                    │
├─────────────────────────────────────────────────────────────┤
│  Tools (2)                        AI-invoked operations     │
│  ├── get_figma_data              Fetch design data          │
│  └── download_figma_images       Download image assets      │
├─────────────────────────────────────────────────────────────┤
│  Prompts (3)                      User-selected templates   │
│  ├── design_to_code              Full design-to-code flow   │
│  ├── analyze_components          Component structure        │
│  └── extract_styles              Style token extraction     │
├─────────────────────────────────────────────────────────────┤
│  Resources (5)                    Lightweight data sources  │
│  ├── figma://help                Usage guide                │
│  ├── figma://file/{key}          File metadata (~200 tok)   │
│  ├── figma://file/{key}/styles   Design tokens (~500 tok)   │
│  ├── figma://file/{key}/components Component list (~300 tok)│
│  └── figma://file/{key}/assets   Asset inventory (~400 tok) │
└─────────────────────────────────────────────────────────────┘

Tools

Tool	Description	Parameters
`get_figma_data`	Fetch simplified design data	`fileKey`, `nodeId?`, `depth?`
`download_figma_images`	Download images and icons	`fileKey`, `nodes[]`, `localPath`

Prompts

Built-in professional prompt templates to help AI generate high-quality code:

Prompt	Description	Parameters
`design_to_code`	Complete design-to-code workflow	`framework?`, `includeResponsive?`
`analyze_components`	Analyze component structure and reusability	-
`extract_styles`	Extract design tokens	-

design_to_code workflow includes:

Project Analysis - Read theme config, global styles, component library
Structure Analysis - Identify page patterns, component splitting strategy
ASCII Layout Blueprint - Generate layout diagram with component and asset annotations
Asset Management - Analyze, download, and organize images/icons
Code Generation - Generate code following project conventions
Accessibility Optimization - Semantic HTML, ARIA labels
Responsive Adaptation - Mobile layout adjustments

Resources

Lightweight data access to save tokens:

# Get file metadata (~200 tokens)
figma://file/abc123

# Get design tokens (~500 tokens)
figma://file/abc123/styles

# Get component list (~300 tokens)
figma://file/abc123/components

# Get asset inventory (~400 tokens)
figma://file/abc123/assets

Resources vs Tools comparison:

Feature	Tools	Resources
Controller	AI auto-invoked	User/client initiated
Token cost	Higher (full data)	Lower (summaries)
Use case	Execute actions	Browse and explore

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        MCP Server                            │
├──────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│  │   Tools     │  │   Prompts   │  │     Resources       │   │
│  │ (2 tools)   │  │ (3 prompts) │  │   (5 resources)     │   │
│  └──────┬──────┘  └─────────────┘  └──────────┬──────────┘   │
│         │                                      │              │
│         └──────────────────┬───────────────────┘              │
│                            ▼                                  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                   FigmaService                         │  │
│  │          API Calls • Validation • Error Handling       │  │
│  └────────────────────────┬───────────────────────────────┘  │
│                           │                                  │
│         ┌─────────────────┴─────────────────┐                │
│         ▼                                   ▼                │
│  ┌─────────────────┐              ┌─────────────────────┐    │
│  │   CacheManager  │              │    Parser + Algo    │    │
│  │  L1: LRU Memory │              │  • Layout Detection │    │
│  │  L2: Disk Store │              │  • Icon Merging     │    │
│  └─────────────────┘              │  • CSS Generation   │    │
│                                   └─────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

Cache System

Two-layer cache architecture significantly reduces API calls:

Layer	Storage	Capacity	TTL	Purpose
L1	Memory LRU	100 nodes / 50 images	5-10 min	Hot data fast access
L2	Disk	500MB	24 hours	Persistent cache

Layout Detection Algorithm

Automatically converts absolute positioning to semantic Flexbox/Grid layouts:

Input (Figma absolute positioning):
┌─────────────────────────┐
│ ■ (10,10)  ■ (110,10)   │
│ ■ (10,60)  ■ (110,60)   │
└─────────────────────────┘

Output (Inferred Grid):
display: grid
grid-template-columns: 100px 100px
grid-template-rows: 50px 50px
gap: 10px

Project Structure

src/
├── algorithms/           # Smart algorithms
│   ├── layout/          # Layout detection (Flex/Grid inference)
│   └── icon/            # Icon merge detection
├── core/                 # Core parsing
│   ├── parser.ts        # Figma data parser
│   ├── style.ts         # CSS style generation
│   ├── layout.ts        # Layout processing
│   └── effects.ts       # Effects handling
├── services/             # Service layer
│   ├── figma.ts         # Figma API client
│   └── cache/           # Multi-layer cache system
├── prompts/              # MCP prompt templates
├── resources/            # MCP resource handlers
├── types/                # TypeScript type definitions
├── utils/                # Utility functions
├── server.ts             # MCP server main entry
└── index.ts              # CLI entry

tests/
├── fixtures/             # Test data
│   ├── figma-data/      # Raw JSON from Figma API
│   └── expected/        # Expected output snapshots
├── integration/          # Integration tests
│   ├── layout-optimization.test.ts  # Layout optimization tests
│   ├── output-quality.test.ts       # Output quality validation
│   └── parser.test.ts               # Parser tests
└── unit/                 # Unit tests
    ├── algorithms/      # Algorithm tests (layout, icon detection)
    ├── resources/       # Resource handler tests
    └── services/        # Service layer tests

scripts/
└── fetch-test-data.ts   # Figma test data fetcher

Documentation

Core Algorithms

English	中文
Layout Detection	布局检测算法
Icon Detection	图标检测算法
Cache Architecture	缓存架构设计

Research Documents

English	中文
Grid Layout Research	Grid 布局研究
Layout Detection Research	布局检测研究

Architecture Documents

English	中文
Architecture	系统架构

Command Line Options

Option	Description	Default
`--figma-api-key`	Figma API token	Required
`--port`	Server port for HTTP mode	3333
`--stdio`	Run in stdio mode	false
`--help`	Show help	-

Contributing

Contributions are welcome!

# Setup
git clone https://github.com/1yhy/Figma-Context-MCP.git
cd Figma-Context-MCP
pnpm install

# Development
pnpm dev          # Watch mode
pnpm test         # Run tests (272 test cases)
pnpm lint         # Lint code
pnpm build        # Build

# Debug
pnpm inspect      # MCP Inspector

# Test with your own Figma data
pnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName>

# Commit (uses conventional commits)
git commit -m "feat: add new feature"

Commit Types

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation
`style`	Code style
`refactor`	Refactoring
`test`	Tests
`chore`	Maintenance

Release Process (Maintainers)

# 1. Update version in package.json and CHANGELOG.md

# 2. Commit version bump
git add -A
git commit -m "chore: bump version to x.x.x"

# 3. Publish to npm (auto runs: type-check → lint → test → build)
npm login --scope=@yhy2001  # if not logged in
pnpm run pub:release

# 4. Create git tag and push
git tag vx.x.x
git push origin main --tags

# 5. Create GitHub Release (optional)
# Go to https://github.com/1yhy/Figma-Context-MCP/releases/new

Testing with Your Own Figma Data

You can test the layout detection and optimization with your own Figma designs:

1. Configure Environment Variables

# Copy the environment template
cp .env.example .env

# Edit .env file with your configuration
FIGMA_API_KEY=your_figma_api_key_here
TEST_FIGMA_FILE_KEY=your_file_key      # Optional
TEST_FIGMA_NODE_ID=your_node_id        # Optional

2. Fetch Figma Node Data

# Method 1: Using command line arguments (recommended)
pnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName>

# Example: Fetch a specific node
pnpm tsx scripts/fetch-test-data.ts UgtwrncR3GokKDIS7dpm4Z 402-34955 my-design

# Method 2: Using environment variables
TEST_FIGMA_FILE_KEY=xxx TEST_FIGMA_NODE_ID=123-456 pnpm tsx scripts/fetch-test-data.ts

Parameters:

Parameter	Description	How to Get
`fileKey`	Figma file identifier	Part after `/design/` in URL, e.g., `UgtwrncR3GokKDIS7dpm4Z`
`nodeId`	Node ID	`node-id=` parameter in URL, e.g., `402-34955`
`outputName`	Output filename	Custom name, e.g., `my-design`

Example URL Parsing:

https://www.figma.com/design/UgtwrncR3GokKDIS7dpm4Z/MyProject?node-id=402-34955
                            ↑ fileKey                              ↑ nodeId

3. Run Tests to Validate Output

# Run all tests
pnpm test

# Run only integration tests (validate layout optimization)
pnpm test tests/integration/

# View output JSON files
ls tests/fixtures/figma-data/

4. Analyze Optimization Results

Tests automatically validate:

Data Compression - Typically >50% compression
Layout Detection - Flex/Grid layout recognition rate
CSS Properties - Redundant property cleanup
Output Quality - Structural consistency checks

If tests fail, the output may not meet expectations. Check error messages to adjust or report an issue.

License

MIT © 1yhy

Acknowledgments

Figma-Context-MCP - Original project
Model Context Protocol - MCP specification
Best-README-Template - README template reference

Made with ❤️ for the AI coding community