用一句话来说Figma MCP 是连接设计稿与 AI 的“数据管道”。以前前端拿到设计稿后要手动量尺寸、取颜色、切图标再一点点还原成代码现在通过 MCP 协议AI 可以直接读取 Figma 文件里的图层、布局和样式数据基于真实结构生成前端代码。这篇文章会从一个前端的视角出发拆解设计数据如何以 JSON 形式流转以及如何把它接入 AI 代码生成链路。适用读者想转 AI 工程化方向的前端开发者正在研究 MCPModel Context Protocol但没有合适案例的人想知道“Figma JSON 结构到底长什么样”的开发者想把设计稿直接变成 React/Vue/HTML 代码的工具爱好者。读完这篇文章你能掌握三件事MCP 的基本原理、Figma 设计数据的 JSON 结构、以及一个从设计稿到前端代码的最小可运行链路。1. 背景为什么前端要关注 Figma MCP1.1 MCP 是什么MCP 全称是 Model Context Protocol翻译过来叫“模型上下文协议”。它是一个开放协议解决的核心问题是让 AI 模型安全地读取外部工具和数据源。你可以把 MCP 理解为 AI 世界的 USB 接口。USB 定义了设备之间如何供电、如何传输数据而 MCP 定义了 AI 应用和外部服务之间如何发现工具、调用工具、获取结果。一个 MCP Server 把某种能力包装成标准接口AI 客户端Claude、Codex、Cursor 以及各种 Agent 应用可以通过标准方式调用这些能力。举个例子。没有 MCP 时想让 AI 读取一个网页链接你需要把网页内容手动复制粘贴到对话里有了 MCPAI 可以直接调用一个fetch_webpage工具自动拿到目标网站内容。MCP 的价值在于让 AI 从“只能聊”变成“能操作”。1.2 Figma MCP 在解决什么问题Figma MCP 就是专门用来读取 Figma 设计数据的 MCP Server。它把 Figma REST API 的能力封装成了 AI 可以调用的工具比如读取某个 Figma 文件的所有节点获取指定页面的图层树返回某个节点的样式、布局、尺寸、颜色返回组件实例和属性信息。对前端来说这意味着 AI 可以用“原生结构数据”来理解设计稿而不是靠截图猜。过去做“设计稿转代码”AI 只能看图片像素判断不准确代码还原度和设计稿差距很大。现在AI 拿到的是包含真实坐标、尺寸、颜色值、字体信息的 JSON 数据准确性明显提高。1.3 当前生态与适用场景Figma MCP 的生态在快速演化常见的接入方向有三种AI 辅助代码生成Claude Desktop、Codex、Cursor 等工具通过 MCP 读取设计稿生成页面代码或组件代码。设计稿数据提取不生成代码只把 Figma 上的设计规范色彩、字体、间距同步成 JSON Token供前端工程使用。自动化质检与文档生成把设计稿结构自动整理成组件清单、接口说明等。这篇文章的重点是第 1 种也就是“设计数据 → JSON → 代码生成”的全链路。2. 核心链路从设计稿到前端代码2.1 传统设计稿还原的痛点先看一下没有 MCP 时前端拿到设计稿后通常要做哪些事打开 Figma 设计稿确认页面尺寸和设备范围逐个图层量尺寸、间距、圆角、字号、颜色手动切图导出图标和图片资源在代码里按设计稿写 CSS、布局和组件反复对比和调整直到“像素级还原”。这套流程重复、琐碎而且非常依赖人的细心程度。尤其是遇到大型设计系统几十个页面、几百个组件人工对照效率很低。2.2 引入 MCP 后的新链路引入 Figma MCP 之后流程变成Figma 设计稿 ↓ Figma REST API 返回文件 JSON ↓ MCP Server 对 JSON 进行解析和精简 ↓ AI 模型拿到结构化设计数据 ↓ 按 Prompt 生成前端代码 ↓ 开发者 review 并接入项目这个链路的前半段是数据管道后半段是 AI 生成能力。前端开发者在前半段有天然优势我们每天都在和 JSON、结构、组件、样式打交道理解设计稿数据比纯后端转 AI 的人更容易。2.3 关键角色文件 Key、节点 ID、JSON 结构要继续往下走必须理解三个概念概念说明示例File KeyFigma 文件 URL 中标识文件的那一段https://www.figma.com/file/AbCdEf123/MyDesign中的AbCdEf123节点 ID页面中某个图层的唯一标识1:2、1:3JSON 结构Figma API 返回的节点树数据包含 type、name、children、styles 等字段这三个概念是后面所有操作的基础尤其是节点 ID。你只想要某个页面或某个组件的数据时不需要拉取整个文件只用节点 ID 精确请求。3. 环境准备与版本说明3.1 需要准备什么操作环境和版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。建议准备以下内容一个 Figma 账号并有一个可以测试的简单文件Node.js 环境建议使用较新的 LTS 版本因为很多 MCP Server 通过npx启动Python 3.9 以上如果你要自己写 MCP Server 示例一个支持 MCP 的 AI 客户端比如 Claude Desktop、Codex、Cursor 等一个代码编辑器用来查看 JSON 和生成项目代码。注意不同 AI 客户端的 MCP 支持方式不一样有的通过 JSON 配置文件有的通过命令行注册后面会分开说明。3.2 获取 Figma 访问令牌Figma MCP 和 Figma API 都需要访问令牌Access Token。获取步骤如下登录 Figma 官网进入账户设置找到 “Security” 或 “Personal access tokens” 板块点击生成新令牌权限建议选择File content: Read-only只读权限足够本次实战使用生成后立刻复制保存令牌只会完整显示一次。拿到令牌后不要把它提交到 Git 仓库也不要写死在业务代码里。建议使用环境变量或本地配置文件管理。3.3 找到你的 Figma File Key打开要测试的 Figma 文件浏览器地址栏的 URL 一般是https://www.figma.com/file/FileKey/FileName比如链接是https://www.figma.com/file/9xYf3KpVrQ/LoginPage那么 File Key 就是9xYf3KpVrQ。如果你要读取文件中的某一个页面或节点还需要节点 ID。在 Figma 中选中一个图层浏览器地址栏末尾会变成/node/1:2这里的1:2就是节点 ID。4. 动手实践最小可运行的 Figma MCP 工作流4.1 先直接调 Figma API理解 JSON 数据在写 MCP 之前强烈建议先用 Python 或 curl 直接调用一次 Figma API亲眼看看返回的 JSON 长什么样。用 Python 写一个最简单读取文件的脚本# 文件路径figma_demo/get_file.py import json import requests FIGMA_TOKEN 你的Figma访问令牌 FILE_KEY 你的文件Key def get_figma_file(file_key: str): url fhttps://api.figma.com/v1/files/{file_key} headers { X-Figma-Token: FIGMA_TOKEN } resp requests.get(url, headersheaders) if resp.status_code 200: return resp.json() else: raise Exception(fFigma API 异常: {resp.status_code}, {resp.text}) if __name__ __main__: data get_figma_file(FILE_KEY) print(json.dumps(data, ensure_asciiFalse, indent2))运行结果会是一个很庞大的 JSON 对象。其中最重要的字段是document它是一棵节点树结构大概如下{ document: { id: 0:0, name: 登录页, type: CANVAS, children: [ { id: 1:2, name: Frame 1, type: FRAME, x: 0, y: 0, width: 375, height: 812, children: [] } ] } }这里的type对应 Figma 的节点类型常见的有FRAME、TEXT、RECTANGLE、ELLIPSE、COMPONENT、INSTANCE。children代表子节点整棵树就是设计稿的图层结构。只读取指定节点也很方便调用 nodes 接口# 文件路径figma_demo/get_node.py import json import requests FIGMA_TOKEN 你的Figma访问令牌 FILE_KEY 你的文件Key NODE_IDS 1:2 def get_figma_node(file_key: str, node_ids: str): url fhttps://api.figma.com/v1/files/{file_key}/nodes params {ids: node_ids} headers { X-Figma-Token: FIGMA_TOKEN } resp requests.get(url, headersheaders, paramsparams) if resp.status_code 200: return resp.json() else: raise Exception(fFigma API 异常: {resp.status_code}, {resp.text}) if __name__ __main__: data get_figma_node(FILE_KEY, NODE_IDS) print(json.dumps(data, ensure_asciiFalse, indent2))这一步非常重要。你会发现 Figma API 返回的数据是“全量且原始”的包含坐标、颜色、字体、布局约束等大量字段。如果把这些数据全部直接丢给 AI不仅浪费 token还会让 AI 抓不住重点。所以MCP Server 的职责并不是简单透传 API 响应而是要做数据精简和结构化。4.2 用 FastMCP 写一个精简版 Figma MCP Server接下来我们用 Python 的 MCP SDK 写一个最小可运行的 MCP Server。它提供两个工具get_figma_file_json读取整个文件的 JSON 结构get_figma_node_json按节点 ID 读取局部结构。代码示例# 文件路径figma_mcp_server/server.py from mcp.server.fastmcp import FastMCP import requests mcp FastMCP(figma-reader) FIGMA_API_URL https://api.figma.com/v1 FIGMA_TOKEN 你的Figma访问令牌 def _headers(): return {X-Figma-Token: FIGMA_TOKEN} mcp.tool() def get_figma_file_json(file_key: str) - dict: 读取 Figma 文件的完整 JSON 结构。 Args: file_key: Figma 文件 URL 中的 File Key。 url f{FIGMA_API_URL}/files/{file_key} resp requests.get(url, headers_headers()) if resp.status_code 200: return resp.json() return {error: resp.status_code, message: resp.text} mcp.tool() def get_figma_node_json(file_key: str, node_ids: str) - dict: 读取 Figma 文件中指定节点的 JSON 结构。 Args: file_key: Figma 文件 URL 中的 File Key。 node_ids: 节点 ID多个用英文逗号分隔例如 1:2,1:3。 url f{FIGMA_API_URL}/files/{file_key}/nodes params {ids: node_ids} resp requests.get(url, headers_headers(), paramsparams) if resp.status_code 200: return resp.json() return {error: resp.status_code, message: resp.text} if __name__ __main__: mcp.run()这段代码的原则用 FastMCP 的mcp.tool()装饰器把普通函数变成 AI 可调用的 MCP 工具函数的 docstring 会被 AI 读取用来判断什么时候调用这个工具所以描述要清晰真实项目中不要直接把 token 写在代码里建议改成读取环境变量。4.3 在 AI 客户端中注册 MCP Server不同客户端的注册方式不同但绝大多数都是修改一个 JSON 配置文件。这里给出一个通用参考模板{ mcpServers: { figma: { command: python, args: [/绝对路径/figma_mcp_server/server.py], env: { FIGMA_TOKEN: 你的Figma访问令牌 } } } }把上面的配置放到你正在使用的 AI 客户端的 MCP 配置文件中。常见位置如下客户端配置文件位置Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonCursor项目目录下的.cursor/mcp.jsonCodex通过codex mcp add命令添加如果你的客户端版本不支持 JSON 配置可以去查对应文档用命令行方式注册。配置完成后重启客户端再打开一个新会话。配置好之后在会话里询问 AI请使用 figma 工具读取文件 key 为 9xYf3KpVrQ 的 design 页面并说明这个页面有哪些主要模块。如果 MCP 注册成功AI 会自动调用get_figma_file_json返回 JSON 后AI 会基于文档内容回答。4.4 设计稿 JSON 到底长什么样我们以一个手机登录页为例看一下精简后的 JSON 结构{ id: 1:2, name: 登录页, type: FRAME, x: 0, y: 0, width: 375, height: 812, children: [ { id: 1:3, name: Logo, type: COMPONENT, x: 147.5, y: 120, width: 80, height: 80 }, { id: 1:4, name: 手机号输入框, type: FRAME, x: 16, y: 260, width: 343, height: 48, layoutMode: HORIZONTAL, children: [ { id: 1:5, name: 占位文本, type: TEXT, characters: 请输入手机号, style: { fontSize: 16, fontFamily: PingFang SC, fontWeight: 400, color: #999999 } } ] }, { id: 1:6, name: 登录按钮, type: RECTANGLE, x: 16, y: 330, width: 343, height: 48, fills: [ { type: SOLID, color: #1677FF } ] } ] }注意几点type能区分文本、形状、容器、组件x、y、width、height表示绝对位置和尺寸layoutMode表示是否为自动布局HORIZONTAL是横向VERTICAL是纵向style里是文本样式fills里是填充颜色真实 API 返回的数据字段比这多得多比如还有scrollBehavior、constraints、effects等。AI 看到这样的 JSON就能准确推断布局一个 375×812 的手机 Frame 里上面有 Logo中间有输入框下面有按钮。基于这些数据生成前端代码的准确率远高于看图写码。4.5 让 AI 基于 JSON 生成前端代码数据有了MCP 工具也有了现在把设计稿交给 AI。下面是一个有效 Prompt 示例请根据以下 Figma JSON 结构生成一个移动端登录页的 React 组件。 要求 1. 使用 Tailwind CSS 实现样式 2. 组件需要响应式宽度最大 480px居中显示 3. 手机号输入框需要有 label、placeholder、清空按钮 4. 登录按钮需要有 loading 状态 5. 导出 TypeScript 类型定义 6. 文件拆分LoginPage.tsx、types.ts。 JSON 数据如下 {在这里粘贴 MCP 返回的精简 JSON}如果你使用的是支持 MCP 的 AI 客户端可以直接让 AI“读取刚才的 JSON 数据”不需要手动复制粘贴。AI 会根据结构生成类似这样的页面代码// 文件路径src/components/LoginPage.tsx import React, { useState } from react; interface LoginPageProps { onSubmit?: (phone: string) void; } export function LoginPage({ onSubmit }: LoginPageProps) { const [phone, setPhone] useState(); const [loading, setLoading] useState(false); const handleSubmit () { setLoading(true); setTimeout(() { setLoading(false); onSubmit?.(phone); }, 1000); }; return ( div classNameflex min-h-screen items-center justify-center bg-gray-50 p-4 div classNamew-full max-w-[480px] rounded-2xl bg-white p-6 shadow-sm div classNameflex justify-center img src/logo.png altLogo classNameh-20 w-20 / /div div classNamemt-6 label htmlForphone classNameblock text-sm font-medium text-gray-700 手机号 /label input idphone typetel value{phone} onChange{(e) setPhone(e.target.value)} placeholder请输入手机号 classNamemt-1 h-12 w-full rounded-lg border border-gray-300 px-4 text-base outline-none focus:border-blue-500 / /div button onClick{handleSubmit} disabled{loading} classNamemt-8 h-12 w-full rounded-lg bg-[#1677FF] text-base font-medium text-white transition hover:bg-blue-600 disabled:opacity-60 {loading ? 登录中... : 登录} /button /div /div ); }这段代码是 AI 从 JSON 结构推导出来的。它正确识别了375×812 的画板对应移动端页面Logo 居中输入框和按钮的宽度一致按钮主色是#1677FF。当然AI 生成的代码不是拿来就能直接用的。组件的交互细节比如表单校验、接口请求需要程序员补全图标资源也需要替换成真实图片。但整体骨架已经非常接近设计稿了。5. 常见问题与排查思路实际开发中配置 Figma MCP 经常遇到各种问题。下面按问题现象、常见原因、解决思路整理成表格问题现象常见原因解决思路MCP Server 在 Codex 中工具注册不上客户端未能启动 MCP 进程先用命令行单独执行python server.py验证进程能启动确认配置文件路径正确重启客户端调用工具时返回 403Figma Token 权限不足或文件未共享检查 Token 权限是否为File content: Read-only确认文件已共享给 Token 所属账号MCP Server 能启动但连不上 Figma API网络不通或者 API 地址错误用 curl 单独请求https://api.figma.com/v1/files/{file_key}验证网络检查 File Key 是否正确返回 JSON 太大AI 上下文超限整个文件节点过多只请求目标节点 ID而不是整个文件在 MCP Server 中做字段精简只保留 name、type、layout、style 等关键字段AI 生成的代码布局和设计稿不一致设计稿中大量绝对定位或图层命名混乱在 Figma 中改用 Auto Layout规范图层命名减少多余分组配置文件修改后不生效客户端缓存或未重启修改完 MCP 配置后必须完全退出并重启客户端部分客户端还需要清理缓存MCP Server 输出乱码编码问题常见于 Windows在 Python 代码中指定输出编码sys.stdout.reconfigure(encodingutf-8)其中“MCP Server 工具注册不上”是最常见的问题。排查顺序建议如下先确认 MCP Server 能独立运行不依赖 AI 客户端再确认配置文件中的command和args路径是否正确然后确认环境变量有没有正确传入最后检查客户端日志不同客户端有不同日志位置可以在官方文档中查找。6. 最佳实践与工程化建议6.1 从设计源头规范数据结构MCP 只能读取设计数据不能代替设计规范。如果设计稿里全都是未分组的矩形、散落的文本、混乱的命名AI 拿到 JSON 也未必能准确理解需求。建议推动设计侧做到使用 Auto Layout 实现布局减少绝对定位图层命名语义化比如login-button、phone-input色彩、字体、间距尽量使用 Design Token 或变量常用组件沉淀为 Component 和 Variant。这些规范不仅对 AI 友好对团队协作也有很大价值。6.2 在 MCP Server 层做数据精简把 Figma API 原始 JSON 直接丢给 AI通常不是好做法。原数据里有很多前端不关心的字段比如constraints、exportSettings、styleOverrideTable。建议在 MCP Server 中增加一个转换函数把原始数据压缩成前端需要的“核心 JSON”。例如只保留以下字段# 文件路径figma_mcp_server/formatter.py REQUIRED_FIELDS { id, name, type, x, y, width, height, layoutMode, children, characters, style, fills } def format_node(node): result {key: value for key, value in node.items() if key in REQUIRED_FIELDS} if children in node and node[children]: result[children] [format_node(child) for child in node[children]] return result这样做有三个好处token 消耗更少、AI 理解更准确、输出更稳定。6.3 安全与权限边界使用 Figma API 时Token 就是访问凭证安全上需要格外注意Token 只读权限足够不要给写权限不要把 Token 硬编码进代码使用环境变量或密钥管理服务涉及企业设计稿时要遵守公司的数据安全规范MCP Server 只启动在本地或可信环境中不要暴露到公网如果 Token 泄漏及时到 Figma 后台吊销并重新生成。6.4 Prompt 工程让 AI 输出更可控同样一份 JSON不同 Prompt 生成出来的代码质量差别很大。推荐在 Prompt 中明确目标技术栈React、Vue、原生 HTML还是 Tailwind文件拆分规则单文件、组件拆分、类型定义是否分离业务约束是否有表单校验、权限、埋点需求样式规范是否必须使用 Design Token、是否支持暗色模式。也可以让 AI 先输出“结构理解”再输出代码第一步用列表描述页面有哪些模块和层级关系 第二步根据模块拆分组件给出组件树 第三步按组件树生成代码。这种两步式 Prompt 能降低 AI 一次生成大量代码时的出错率。7. 建议的下一步方向如果你看完这篇文章建议先不用急着搭建完整平台。可以找一个只有单个页面的设计稿手动完成一次“Figma API → JSON → AI 生成代码”的全流程跑通后再逐步加功能。后续值得继续研究的点包括如何把 Figma 中的组件库转换成前端组件库代码如何把 Design Token 同步到前端样式变量实现跨端一致性如何在团队内部搭建一个统一的 MCP Server而不是每个人本地配一遍如何把 MCP 生成的代码接入现有的组件规范和 lint 流程。Figma MCP 目前还处在快速演进阶段配置方式、Server 实现、客户端支持都可能随时变化。最好的学习方式不是等一个“标准答案”而是先把最小链路跑通再在真实项目中持续迭代。如果有条件动手写一个属于自己的 MCP Server 会很有帮助因为理解协议本身比记住某个工具用法更长久。