使用说明

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=<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

用法示例

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

文档

核心算法

English	中文
布局检测	布局检测算法
图标检测	图标检测算法
高速缓存体系结构	缓存架构设计

研究文件

English	中文
网格布局研究	Grid 布局研究
布局检测研究	布局检测研究

架构文件

English	中文
建筑	系统架构

命令行选项

选项	描述	默认值
`--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 <fileKey> <nodeId> <outputName>

# 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        # Optional

2.获取Figma节点数据

# 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

参数：

参数	说明	如何获取
`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                              ↑ nodeId

3.运行测试以验证输出

# 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