Figma MCP

Name: Figma MCP
Author: 1yhy

本地服务

github.com/1yhy媒体与设计3047 周前更新

代码仓库

关于 Figma MCP

Figma Context MCP 是一个 MCP 服务，将 Figma 设计数据提供给 Cursor、Windsurf、Cline 等 AI 编码工具。它面向需要从设计稿生成代码的开发者，并通过布局推断和缓存优化数据结构。

主要功能

01布局检测，推断 Flexbox 与 Grid
02合并矢量图层为可导出图标
03将 Figma 样式转换为 CSS
04两层缓存（内存与磁盘）减少 API 调用
05内置设计转代码提示词模板

适用场景

01让 AI 编码工具依据 Figma 设计实现页面
02批量下载设计稿中的图片与图标
03提取设计令牌与组件信息

MCP 相关

该服务通过 MCP 向客户端暴露 get_figma_data、download_figma_images 等工具，以及设计转代码提示词和 figma:// 资源。

#figma #design-integration #ai-tools

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "figma-context-mcp-1yhy": {
      "command": "npx",
      "args": [
        "-y",
        "figma-mcp"
      ]
    }
  }
}

启动命令npx -y figma-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmfigma-mcpstdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
url	string	是	要添加的 Figma 文件的 URL

详细介绍

Figma Context MCP

将 Figma 设计无缝集成到 AI 编码工具中的 MCP 服务

功能 • 快速开始 • MCP 功能 • 架构 • 文档 • 中文文档

这是什么？

Figma Context MCP 是一个 Model Context Protocol (MCP) 服务，可将 Figma 设计与 Cursor、Windsurf 和 Cline 等 AI 编码助手连接起来。

AI 工具能够直接访问 Figma 设计数据后，首次生成的代码就会更加准确，远胜于使用屏幕截图。

注意：此项目基于 Figma-Context-MCP，并对数据结构和智能布局检测算法进行了优化。

功能

核心功能

功能	说明
智能布局检测	自动从绝对定位推断 Flexbox/Grid 布局
图标合并	智能地将矢量图层合并为可导出的单个图标
CSS 生成	将 Figma 样式转换为简洁、实用的 CSS
图像导出	下载图像和图标，并为其设置合适的名称
多层缓存	L1 内存缓存 + L2 磁盘缓存，减少 API 调用
设计转代码提示词	内置专业提示词模板，引导 AI 生成代码
轻量级资源访问	Resources API 提供低 Token 消耗的数据访问

主要改进

功能	改进前	改进后
图标导出	约 45 个零散图标	合并为 2 个（减少 96%）
布局检测	手动绝对定位	自动推断 Flexbox/Grid 布局
CSS 输出	原始值	移除默认值并进行优化
API 调用	每次请求都调用	24 小时智能缓存

快速开始

前提条件

Node.js >= 18.0.0
可访问 API 的 Figma 账户

安装

通过 Smithery（推荐）

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 账户设置
滚动到“Personal access tokens”
点击“Create new token”
复制令牌

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 模式（本地开发）

# 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	中文
Grid 布局研究	Grid 布局研究
布局检测研究	布局检测研究

架构文档

English	中文
架构	系统架构

命令行选项

Option	Description	Default
`--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"

提交类型

Type	Description
`feat`	新功能
`fix`	修复错误
`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

参数：

Parameter	Description	How to Get
`fileKey`	Figma 文件标识符	URL 中 `/design/` 后面的部分，例如 `UgtwrncR3GokKDIS7dpm4Z`
`nodeId`	节点 ID	URL 中的 `node-id=` 参数，例如 `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 属性 - 清理冗余属性
输出质量 - 结构一致性检查

如果测试失败，输出可能不符合预期。请检查错误消息，以便调整或报告问题。

许可证

MIT © 1yhy

致谢

Figma-Context-MCP - 原始项目
Model Context Protocol - MCP 规范
Best-README-Template - README 模板参考

为 AI 编码社区倾情打造 ❤️

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。