Figma MCP 使用指南：让 AI 直接"看懂"你的设计稿

适用读者：前端开发者、UI/UX 设计师 |
本文基于 Figma MCP Plugin v2.2.12 官方技能文件编写。Figma MCP 目前仍在快速迭代中，建议关注官方更新以获取最新功能和 API 变更。

一、为什么写这篇指南？

先讲一个你可能很熟悉的场景：

设计师在 Figma 里精雕细琢了一套页面，颜色、间距、字体、阴影全都调好了，丢给前端一个链接。前端打开一看，开始手动量像素、取色值、对着截图一行行写 CSS。这个过程里，设计意图的损耗是必然的–渐变角度差了两度，阴影扩散半径多了 2px，行高跟设计稿不完全一致。往往要来回沟通好几轮，才能让开发产物"差不多像"设计稿。

Figma MCP 要解决的就是这个问题。

它相当于在 Figma 和你的代码编辑器之间架了一座桥。借助 MCP（Model Context Protocol，模型上下文协议），AI 编程助手（比如 Claude Code）可以直接"读"你的 Figma 设计文件，提取出结构化的设计信息–布局层级、颜色变量、组件属性、间距数值–然后自动生成对应的前端代码。反过来，你也可以把已经写好的页面"推"回 Figma，在同一个平台上对照设计和实现。

说白了就是：以前是设计师给图、前端对着图写代码；现在是 AI 直接消化设计稿，输出代码骨架，你只需要做最后的调整和确认。

这篇文章会从头到尾把 Figma MCP 讲清楚。读完你会知道怎么配环境、有哪些工具可以用、怎么选工作流、以及有哪些坑需要避开。

二、先搞清楚几个概念

2.1 MCP 是什么？

MCP 的全称是 Model Context Protocol。你可以把它理解成 AI 助手的"USB-C 接口协议"–不同的外部系统（数据库、API、文件系统，以及这里的 Figma）只要实现了这个协议，AI 就能用统一的方式跟它们交互。

打个比方：没有 MCP 之前，AI 要想操作 Figma，你得手动导出图片→上传给 AI→AI 看图猜结构→生成代码。有了 MCP 之后，AI 直接调用 Figma 的 API，拿到的是结构化数据，不用再"猜"了，信息传递高效且准确。

2.2 Figma MCP 是什么？

Figma MCP 是 Figma 官方提供的一套 MCP 服务器插件。安装之后，你的 AI 编程助手就多出了 18 个工具和 8 个技能，专门用来跟 Figma 打交道。

它支持双向工作流：

  • 设计 → 代码（Design to Code）：从 Figma 提取设计信息，生成前端代码
  • 代码 → 设计（Code to Design）：把写好的页面推送到 Figma，保持设计和实现的同步
  • Code Connect：建立 Figma 组件与代码组件之间的映射关系，让两端"知道彼此的存在"

2.3 它能覆盖哪些 Figma 产品？

Figma MCP 支持三种编辑器类型：

编辑器类型 URL 特征 能干什么
Design figma.com/design/... 完整支持：组件、变量、样式、页面管理、设计系统构建
FigJam figma.com/board/... 白板内容读写、便签、连接线、图表生成
Slides figma.com/slides/... 演示文稿创建和编辑、幻灯片布局管理

大部分前端日常用的都是 Design 模式，后面会重点讲这个。

三、方案对比：有 Figma MCP 和没有的差别

用一个表来对比三种工作方式：

环节 传统方式 有 AI 但没有 MCP 有 Figma MCP
获取设计信息 设计师导出标注/切图 AI 看截图猜测颜色、间距 AI 直接读取结构化数据（变量、节点树）
代码生成 手写 CSS，逐像素还原 AI 凭经验生成，准确度不稳定 AI 拿到精确数值，代码接近"一比一还原"
迭代更新 设计师改稿→重新标注→前端改代码 重新截图→重新描述→AI 重新生成 增量读取变更，精准更新对应代码
反向同步 不可能 不可能 可以把代码中的组件推回 Figma
设计系统一致性 靠人沟通和文档约定 靠 prompt 工程提示 Code Connect 自动维护映射关系

一句话总结升级体验：从"看图说话"进化到了"读数据做事"。

四、配置步骤：把 Figma MCP 跑起来

4.1 前提条件

  • 安装了 Claude Code（或其他支持 MCP 的 AI 编程工具）
  • 有一个 Figma 账号（需要登录认证）
  • 安装 Figma 桌面客户端（部分功能需要桌面端配合）

4.2 安装 Figma MCP 插件

在 Claude Code 中安装 Figma MCP 插件：

# 在 Claude Code 中注册 Figma MCP 插件
claude mcp add figma --plugin figma

安装完成后，执行以下命令确认插件已成功加载：

claude mcp list

你应该能在输出中看到 figma 相关的条目，包含 18 个工具。

4.3 认证 Figma 账号

首次使用时，Figma MCP 会要求你登录 Figma 账号进行授权。运行以下命令检查认证状态：

# 让 AI 调用 whoami 工具验证身份

在 Claude Code 会话中，你可以直接说"帮我在 Figma 上检查一下我登录了没有"，AI 会调用 whoami 工具返回你的账号信息和可用的团队（plans）。

whoami 返回的内容里有一个关键字段：planKey（格式像 team::1234567890 或 organization::1234567890）。后续创建新文件时需要用到它。

4.4 配置要点

几个关键配置项的说明：

  • clientLanguages：告诉 MCP 你期望输出什么语言的代码（如 typescript,html,css）。这会影响 get_design_context 返回的代码风格。
  • clientFrameworks：指定目标框架（如 react,vue），同样影响代码生成结果。
  • planKey：团队或组织标识，创建文件时必须提供。

五、核心工具详解

Figma MCP 提供了 18 个工具，但日常使用不需要全部记住。这里按工作方向归类，挑最常用的讲。

5.1 设计→代码方向（Design to Code）

这个方向有 6 个工具，你只需要记住一个核心的：

5.1.1 get_design_context —— 主力选手

这是 Design-to-Code 场景下最重要的工具。给一个 Figma 节点的 ID，它返回：

  • 参考代码：适配你指定语言/框架的代码片段
  • 截图：节点的视觉预览
  • 元数据：布局信息、层级结构
  • 资产下载 URL：用到的图片、图标资源
# 使用方式（通过 AI 自然语言触发）
"帮我读取这个 Figma 节点的设计信息：
 https://figma.com/design/ABC123/MyDesign?node-id=12-34
 用 React + TypeScript 实现"

AI 会自动从 URL 中提取 fileKey（ABC123）和 nodeId（12:34，注意 URL 里的 - 要转成 :），然后调用 get_design_context。

5.1.2 辅助工具的定位
工具 什么时候用
get_screenshot 需要检查设计稿的视觉效果，或者发给同事确认时。可以指定分辨率（最大 65536px）
get_metadata 快速了解文件整体结构。不传 nodeId 时返回所有页面的列表，适合"这个文件里都有什么"的场景
get_variable_defs 提取设计令牌（Design Tokens），比如 {'color/primary': '#3B82F6'}。做设计系统对接时必用
get_libraries 查看文件关联了哪些设计库。在做组件复用分析时有用
search_design_system 在设计系统里搜索组件、变量或样式。比如"找一下有没有现成的 Button 组件"

5.2 代码→设计方向（Code to Design）

5.2.1 use_figma —— 万能写入工具

这是反向工作流的核心。它通过执行 Figma Plugin API 的 JavaScript 代码来操作设计文件。你可以用它：

  • 创建 Frame、Text、Rectangle 等节点
  • 设置自动布局（Auto Layout）
  • 管理组件和变体
  • 创建和绑定设计变量
  • 修改样式属性

每次调用最多 50000 字符的代码。因为是直接执行 JS，所以灵活性极高。

最重要的几条规则（避坑必读）：

  1. 颜色用 0-1 范围，不是 0-255。红色是 {r: 1, g: 0, b: 0}，不是 {r: 255, g: 0, b: 0}。
  2. 写文字前必须先加载字体：await figma.loadFontAsync({family: "Inter", style: "Semi Bold"})，否则会报错。注意 “Semi Bold” 中间有空格，不是 “SemiBold”。
  3. 切换页面用异步方法：await figma.setCurrentPageAsync(page)，不能用 figma.currentPage = page。
  4. fills 和 strokes 是只读数组，不能直接 push，要克隆→修改→重新赋值。
  5. 每次调用控制在 10 个逻辑操作以内，增量构建比一次写一大坨更可靠。
  6. 必须返回所有创建/修改的节点 ID。

注意：使用 use_figma 前必须先加载 figma-use 技能。这不是可选的，跳过会导致常见且难以排查的错误。

5.2.2 generate_figma_design —— 网页截图进 Figma

如果你已经把页面写好了（不管是本地 dev server 还是线上地址），这个工具可以把它像素级精确地捕获到 Figma 里。

典型用法是跟 use_figma 并行配合：

  • use_figma 用设计系统组件构建页面结构
  • generate_figma_design 同时捕获像素级截图作为视觉参考
  • 两者对齐后，删除截图，保留组件化版本

这种"双路并进"的策略，既保证了组件规范性，又有像素级精度做参考。

5.2.3 文件管理和资源工具
工具 用途
create_new_file 创建新的 Figma 文件（Design / FigJam / Slides）。需要先通过 whoami 获取 planKey
upload_assets 上传图片到 Figma 文件。支持 PNG/JPG/GIF/WebP，单个最大 10MB。在 FigJam 中这是唯一添加图片的方式

5.3 Code Connect：让设计和代码"知道彼此"

Code Connect 是 Figma MCP 里最容易被忽视、但长期价值最大的部分。它做的事情很简单：告诉 Figma “这个设计组件对应代码里的哪个文件”。

建立映射之后的效果：

  • AI 读 Figma 设计时，直接输出你项目里的真实组件名，而不是泛泛的 <button> 标签
  • 设计系统有了"双向追溯"–从设计稿能跳到代码，从代码能追溯到设计稿
  • 团队协作时不会出现"这个组件代码里叫 Button，设计稿里叫 btn/primary"的命名分歧

相关工具链：

工具 作用
get_code_connect_suggestions 扫描节点，告诉你有哪些组件还没建立映射，并给出 AI 建议的匹配
get_context_for_code_connect 获取组件的属性定义（文本、布尔、变体、实例交换、插槽类型）
get_code_connect_map 查看已有映射关系
add_code_connect_map 建立单个映射
send_code_connect_mappings 批量提交映射（先建议→确认→批量保存）

5.4 图表工具

generate_diagram

用 Mermaid.js 语法生成图表，输出到 FigJam。支持的图表类型：

  • 流程图（flowchart）
  • 序列图（sequenceDiagram）
  • 状态图（stateDiagram）
  • 甘特图（gantt）
  • ER 图（erDiagram）

不支持的类型：饼图、思维导图、类图、时间线、维恩图。

get_figjam

读取 FigJam 文件的结构。注意 FigJam 不支持 get_metadata，用这个替代。

六、8 个技能：什么时候用哪个

技能（Skills）是指导 AI 如何正确使用 MCP 工具的知识模块。你可以把它们理解成"操作手册"–告诉 AI 什么情况下该用什么工具、什么顺序调用、有什么注意事项。

# 技能名称 类型 什么时候触发
1 figma-use 必需 每次调用 use_figma 之前必加载。所有 Figma 写入操作的基础
2 figma-generate-design 场景技能 把应用页面/视图翻译到 Figma（设计系统组件优先）
3 figma-generate-library 场景技能 从代码库构建完整的设计系统（变量→组件→文档→QA）
4 figma-code-connect 场景技能 创建和维护 .figma.ts 模板文件，映射组件关系
5 figma-generate-diagram 必需 每次调用 generate_diagram 之前必加载
6 figma-use-figjam 场景技能 在 FigJam 文件中使用 use_figma 时
7 figma-use-slides 场景技能 在 Slides 文件中使用 use_figma 时
8 figma-create-new-file 必需 每次调用 create_new_file 之前必加载

三个标记为"必需"的技能是硬性前提，跳过的后果通常是莫名其妙的报错。你可以把这类比成"开车前必须系安全带"–不走这个流程也能启动，但迟早会出问题。

当多个技能需要组合使用时，按这个顺序加载：

  1. figma-create-new-file（如需创建新文件）
  2. figma-use（任何写入操作前）
  3. 领域技能（如 figma-generate-design / figma-code-connect）
  4. figma-generate-diagram（如需生成图表）

七、实战案例

7.1 案例一：从设计稿生成前端页面

场景：设计师在 Figma 里完成了一个登录页，你需要用 React + Tailwind CSS 实现。

步骤：

  1. 获取设计上下文：把 Figma 链接丢给 AI，让它调用 get_design_context。指定 clientLanguages: "typescript,html,css" 和 clientFrameworks: "react"。

  2. 提取设计令牌：调用 get_variable_defs 获取颜色、间距、字号等变量值。比如设计稿用的是 --color-primary: #3B82F6，你的 Tailwind 配置就能直接用这个值。

  3. 检查可复用组件：调用 search_design_system 看看有没有现成的 Button、Input 组件。如果有 Code Connect 映射，AI 会直接生成你项目里的组件引用。

  4. 截图验证：调用 get_screenshot 拿到设计稿的视觉参考，写代码时对照着看。

  5. 生成代码：AI 综合以上信息生成 React 组件代码。因为有精确的间距、颜色数据，生成的代码基本不需要大幅调整。

类比：这就像餐厅后厨拿到了一张标注了精确分量的菜谱，而不是一张模糊的成品照片。照着做就行，不用猜"大概放多少盐"。

7.2 案例二：把已有页面同步到 Figma

场景：你已经用 React 实现了一个 Dashboard 页面，现在想让它在 Figma 里也有对应版本，方便设计师做后续迭代。

步骤：

  1. 先加载技能：加载 figma-use 和 figma-generate-design。

  2. 搜索设计系统：调用 search_design_system 找到项目中已有的设计系统组件（Button、Card、Table 等），获取它们的组件 Key。

  3. 并行执行：

    • use_figma：用设计系统组件搭建页面结构
    • generate_figma_design：捕获线上页面的像素级截图

  4. 对齐与收尾：将 use_figma 构建的组件版本与截图对齐，确保视觉一致。然后把截图删除（它只是临时的视觉参考），保留组件化版本。

  5. 建立 Code Connect：如果页面中有自定义组件，用 add_code_connect_map 建立映射关系，形成闭环。

7.3 案例三：从代码库构建设计系统

场景：项目里已经有一套成熟的组件库（比如基于 Ant Design 或自研），你想在 Figma 里也建立一套对应的设计系统，让设计师和开发者使用统一的语言。

步骤概要（这是一个五阶段的大型工作流，需要 20-100+ 次 use_figma 调用）：

  1. Phase 0 - 发现：分析代码库中的组件和设计令牌 → 检查 Figma 现有文件 → 锁定范围 → 每个阶段结束都需要用户确认
  2. Phase 1 - 基础：创建变量集合（原始值）→ 语义变量（如 color-bg-primary → white） → 设置代码语法 → 创建样式
  3. Phase 2 - 文件结构：搭建页面骨架（Cover、Getting Started、Foundations、Components、Utilities）
  4. Phase 3 - 组件：按依赖顺序逐个构建（原子组件 → 组合组件），每个组件一个页面
  5. Phase 4 - 集成与 QA：Code Connect 映射、无障碍审计、命名规范审计、未绑定变量审计

这个过程比较重，只推荐在设计系统从零搭建或大规模重构时使用。日常小修小补直接用 use_figma 就够了。

八、常见陷阱与避坑指南

以下是实际使用中最容易踩的坑，来自官方文档的常见错误汇总：

8.1 use_figma 经典错误

你写的 报错/现象 正确做法
figma.notify("hello") "not implemented" 用 return 输出数据，别用 notify
{r: 255, g: 0, b: 0} 颜色不对（太亮或溢出） 除以 255：{r: 1, g: 0, b: 0}
figma.currentPage = page 页面切换不生效 用 await figma.setCurrentPageAsync(page)
没加载字体就写文字 字体写入错误 先 await figma.loadFontAsync({...})
在 FigJam 里调 figma.createPage() TypeError FigJam 用 Section 组织内容
新节点位置重叠 叠在 (0,0) 上 先扫描现有节点坐标，再放到空白位置
先设 FILL 再 appendChild FILL 设置无效 先 appendChild 再设 FILL
fills 直接 push 不生效 克隆数组 → 修改 → 重新赋值

8.2 编辑器差异要注意

同一个 API 在不同编辑器里表现不同：

  • figma.createPage() 只在 Design 中可用，FigJam 和 Slides 中会直接 TypeError
  • get_metadata 只在 Design 中可用，FigJam 用 get_figjam，Slides 用只读 use_figma 脚本
  • 图片上传：Design 可以用 upload_assets 或 figma.createImage()，但 FigJam 只能用 upload_assets
  • 变量和样式：Design 完整支持，FigJam 不支持，Slides 部分支持（主题变量）

8.3 工作流注意事项

  • 不要跳过必需技能：figma-use、figma-create-new-file、figma-generate-diagram 这三个是硬性前置条件
  • 增量优于一次性：一次 use_figma 调用的代码不要超过 10 个逻辑操作。拆成多步，每步验证
  • 返回节点 ID：每次调用都返回创建/修改的节点 ID，后续步骤需要用到
  • 设计系统构建要有检查点：图里已经画出来了，每个 Phase 结束应该停下来让设计师或团队确认方向

九、总结

Figma MCP 做的事情，本质上是把"设计"和"开发"之间的信息传递从模拟信号升级成了数字信号。

在传统流程里，设计稿到代码的转换是一条有损链路–设计师的意图经过导出、标注、沟通、理解层层衰减。Figma MCP 把这条链路变成了结构化的数据通道：AI 从 Figma 里直接读取精确的设计数据，生成高质量的代码骨架，同时能把代码的变化同步回 Figma。

对于前端开发者，这意味着少花时间在"猜这个间距是 8px 还是 12px"上，多花时间在实现业务逻辑上。对于设计师，这意味着交付的设计稿能被更精准地还原，减少反复校对的工作量。

工具永远不是银弹。Figma MCP 不会自动处理复杂的交互逻辑、不会替代你跟设计师的沟通、也不会帮你做技术决策。但它会让这些事变得更顺畅。试试看吧。

# figma # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

卡帕西 AI 编程神级指令！Codex / Claude / Cursor 通用 AGENTS.md 保姆级教程

avatar AtomGit开源社区
cover

山东大学软件学院创新实训——MarketClaw（五）：从功能原型到可运行闭环的阶段性推进

avatar AtomGit开源社区
cover

Java CountDownLatch 用法和源码解析

avatar AtomGit开源社区