Figma Context MCP
MCP server for seamless Figma design integration with AI coding tools
Features • Quick Start • MCP Capabilities • Architecture • Documentation • 中文文档
______________________________________________________________________
这是什么？
Figma上下文MCP是一个 模型上下文协议（MCP） 将Figma设计与AI编码助手连接起来的服务器，如 光标, 帆板运动，以及 克莱恩.
当人工智能工具可以直接访问Figma设计数据时，它们在第一次尝试时就会生成更准确的代码，远远好于使用屏幕截图。
备注：本项目基于 Figma上下文MCP，具有优化的数据结构和智能布局检测算法。
特性
核心能力
| 能力 | 描述 |
|---|---|
| 智能布局检测 | 根据绝对定位自动推断Flexbox/Grid布局 |
| 图标合并 | 智能地将矢量层合并为单个可导出图标 |
| CSS生成 | 将Figma样式转换为干净、可用的CSS |
| 图像导出 | 下载具有正确命名的图像和图标 |
| 多层缓存 | 一级内存+二级磁盘缓存，减少API调用 |
| 设计到代码提示 | 内置专业提示模板，指导AI代码生成 |
| 轻量级资源访问 | 资源API提供低令牌数据访问 |
关键改进
| 特征 | 之前 | 之后 |
|---|---|---|
| 图标导出 | ~45个碎片 | 2个合并（减少96%） |
| 布局检测 | 手动绝对 | 自动Flexbox/Grid推理 |
| CSS输出 | 原始值 | 优化并删除默认值 |
| API调用 | 每次请求 | 24小时智能缓存 |
快速开始
先决条件
- Node.js>=18.0.0
- 具有API访问权限的Figma帐户
安装
史密斯路（推荐）
npx -y @smithery/cli install @1yhy/Figma-Context-MCP --client claude通过npm
npm install -g @yhy2001/figma-mcp-server来源
git clone https://github.com/1yhy/Figma-Context-MCP.git
cd Figma-Context-MCP
pnpm install
pnpm build配置
1.获取Figma API代币
- 首选 Figma帐户设置
- 滚动到“个人访问令牌”
- 点击“创建新令牌”
- 复制令牌
2.配置您的AI工具
Cursor / Windsurf / Cline
添加到MCP配置文件中：
{
"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= pnpm start
# Or via global install
figma-mcp --figma-api-key= --port=3333
# Connect via SSE
# URL: http://localhost:3333/sse用法示例
Please implement this Figma design: https://www.figma.com/design/abc123/MyDesign?node-id=1:234
Use React and Tailwind CSS.______________________________________________________________________
MCP能力
此服务器提供完整的MCP功能支持：
┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────────────────┘工具
| 工具 | 说明 | 参数 |
|---|---|---|
get_figma_data | 获取简化设计数据 | fileKey, nodeId?, depth? |
download_figma_images | 下载图像和图标 | fileKey, nodes[], localPath |
提示
内置专业提示模板，帮助AI生成高质量代码：
| 提示 | 说明 | 参数 |
|---|---|---|
design_to_code | 完成从设计到编码的工作流程 | framework?, includeResponsive? |
analyze_components | 分析组件结构和可重用性 | - |
extract_styles | 提取设计标记 | - |
design_to_code工作流程包括：
- 项目分析 -读取主题配置、全局样式、组件库
- 结构分析 -识别页面模式、组件拆分策略
- ASCII布局蓝图 -生成带有组件和资产注释的布局图
- 资产管理 -分析、下载和组织图像/图标
- 代码生成 -按照项目约定生成代码
- 可访问性优化 -语义HTML、ARIA标签
- 响应式适应 -移动布局调整
资源
轻量级数据访问以节省令牌：
# 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资源与工具比较：
| 功能 | 工具 | 资源 |
|---|---|---|
| 控制器 | AI自动调用 | 用户/客户端启动 |
| 代币成本 | 较高（完整数据） | 较低（摘要） |
| 用例 | 执行操作 | 浏览和探索 |
______________________________________________________________________
建筑
┌──────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────────┘ │
└──────────────────────────────────────────────────────────────┘缓存系统
双层缓存体系结构显著减少了API调用：
| 层 | 存储 | 容量 | TTL | 用途 |
|---|---|---|---|---|
| L1 | 内存LRU | 100个节点/50个图像 | 5-10分钟 | 热数据快速访问 |
| L2 | 磁盘 | 500MB | 24小时 | 持久缓存 |
布局检测算法
自动将绝对定位转换为语义Flexbox/Grid布局：
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______________________________________________________________________
项目结构
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______________________________________________________________________
文档
核心算法
研究文件
架构文件
______________________________________________________________________
命令行选项
| 选项 | 描述 | 默认值 |
|---|---|---|
--figma-api-key | Figma API令牌 | 必需 |
--port | HTTP模式的服务器端口 | 3333 |
--stdio | 在stdio模式下运行 | false |
--help | 显示帮助 | - |
______________________________________________________________________
贡献
欢迎投稿！
# 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
# Commit (uses conventional commits)
git commit -m "feat: add new feature"提交类型
| 类型 | 描述 |
|---|---|
feat | 新功能 |
fix | Bug修复 |
docs | 文件 |
style | 代码样式 |
refactor | 重构 |
test | 测试 |
chore | 维护保养 |
发布流程（维护人员）
# 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使用您自己的Figma数据进行测试
您可以使用自己的Figma设计测试布局检测和优化：
1.配置环境变量
# 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 # Optional2.获取Figma节点数据
# Method 1: Using command line arguments (recommended)
pnpm tsx scripts/fetch-test-data.ts
# 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参数：
| 参数 | 说明 | 如何获取 |
|---|---|---|
fileKey | Figma文件标识符 | 后面的部分 /design/ 在URL中。， UgtwrncR3GokKDIS7dpm4Z |
nodeId | 节点ID | node-id= URL中的参数。， 402-34955 |
outputName | 输出文件名 | 自定义名称，例如。， my-design |
URL解析示例：
https://www.figma.com/design/UgtwrncR3GokKDIS7dpm4Z/MyProject?node-id=402-34955
↑ fileKey ↑ nodeId3.运行测试以验证输出
# 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.分析优化结果
测试自动验证：
- 数据压缩 -通常压缩率>50%
- 布局检测 -Flex/Grid布局识别率
- CSS属性 -冗余属性清理
- 输出质量 -结构一致性检查
如果测试失败，输出可能不符合预期。检查错误消息以调整或报告问题。
______________________________________________________________________
许可证
麻省理工学院 © 1个月
致谢
- Figma上下文MCP -原始项目
- 模型上下文协议 -MCP规范
- 最佳README模板 -README模板参考
______________________________________________________________________
Made with ❤️ for the AI coding community