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.
Related MCP server: Figma MCP Server
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
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
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"
}
}
}
}
# 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
Research Documents
Architecture Documents
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
