Figma Context
Model Context Protocol server for Figma integration with smart position info
Ask AI about Figma Context
Powered by Claude ยท Grounded in docs
I know everything about Figma Context. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
