最近在做 AI 编码工具和设计稿联动时最大的卡点不是模型不会写代码而是 AI 拿不到设计稿里的结构化信息。截图只能看到像素直接导出 JSON 又太大太重。绕了一圈后我决定自己写一个 Figma MCP 服务器把设计稿变成 AI 可以按需查询的结构化上下文。这篇复盘是“边飞边造引擎”的真实过程适合正在折腾 AI 编程工具、希望让设计稿直接驱动代码生成的工程师尤其是往 AI Engineer 方向走的同学。如果你只是想快速体验社区里已经有 open figma mcp 这类现成实现。但如果你打算把 Figma 接入自己的项目只看现成方案还不够。真正需要理解的是MCP 服务器和 Figma API 之间怎么衔接、返回给模型的内容怎么设计、遇到权限和缓存问题时从哪里查起。下面按一次实际落地的顺序拆开写。1. 先搞清楚Figma MCP 服务器到底解决什么问题1.1 设计稿到 AI 世界之间的间隙MCP 是模型上下文协议。它定义了一套方式让 AI 工具通过客户端去调用外部功能。Figma MCP 服务器就是把 Figma 文件里的节点暴露成一组可调用的工具。比如“读取某个画板的子节点”“读取文本图层内容”“读取某个 frame 的尺寸和样式”。这类能力解决的是设计稿与 AI 模型之间的信息断层。正常情况下AI 编程工具要照着设计稿生成页面通常得靠人把设计稿切成截图再写一大段文字描述主按钮在哪里、宽度多少、背景色是什么、间距多大。这种做法有两个问题截图是像素模型只能看到形状和颜色看不到图层名、组件名、字号、精确间距、填充颜色这些结构化数据。人工描述效率太低。一个登录页就要写几百字一个多页面的后台系统很难靠 prompt 喂进去。Figma MCP 服务器可以按需把设计稿节点转成文本结构。模型需要哪个 frame就调哪个工具不用把整张设计稿塞进上下文。1.2 “边飞边造引擎”的真实含义这个项目的标题叫“边飞边造引擎”很多人以为是在说快速交付。其实核心是另一件事不是先把服务器功能做完再接入业务而是在真实业务推进过程中用最小可用版本跑通一条关键路径再根据实际使用情况逐步加功能。我的路线是这样先用最少的代码跑通“AI 能读取一个 frame 里的文本和坐标”这条链路。放进真实的 AI 编码工具里让它基于某个设计稿生成页面骨架。发现问题比如坐标不够清楚、多余的组件信息太多、缓存不好使再回头改服务器。验证稳定之后再扩展组件实例、样式变量、图片导出、多文件批量处理。这种开发方式最大的好处是每一步改动都有人用、有真实任务去验证。不会出现花两周做了一堆接口最后发现 AI 根本不需要的情况。1.3 直接调用 Figma API 不行吗当然可以。Figma 本身有 REST API能读文件、读节点、导出图片。问题不在于读不到而在于“谁来读、读完之后怎么给模型”。AI 编码工具不是为 Figma API 设计的。它不知道你的 token 存在哪不知道文件 key 怎么传不知道返回的原始 JSON 里哪些字段对生成代码有用。MCP 的价值是让这些操作变成工具并且把参数和返回格式描述清楚。模型看到的是一个带有说明的函数而不是一份需要自己理解的接口文档。所以不是“MCP 比 API 更强”而是“MCP 让 API 更容易被 AI 使用”。这一点想清楚了后面设计服务器时就不会跑偏。2. 架构取舍不要一上来就做“全量 Figma 转 JSON”2.1 现有能力盘点能读什么再决定做什么Figma 的节点结构大致是文件file下面有画布canvas画布下面有画板frame画板下面再挂图层。每个图层都有类型、名称、坐标、尺寸、可见性、填充、字体等属性。在动手写服务器之前要先盘点自己的真实需求。我的建议是列出几个“AI 必须回答的问题”再决定要读哪些字段。常见的问题包括这个页面有哪些顶级区块这个按钮的宽度、高度和圆角是多少输入框的 placeholder 是什么主色是哪个 token 或色值文本图层的字号和字重是多少哪些图层是隐藏的生成代码时要跳过这些问题决定了你需要调用的 API 和输出格式。不需要在一开始就把所有字段都支持。我自己的第一版只做了三件事读取文件基本信息、按节点 ID 读取某个画板下的子节点、把节点格式化成简短的文本。后续才慢慢加上样式变量、图片导出和组件实例来源。2.2 最小闭环只做三件事取文件、按节点读取、输出结构化文本全量转 JSON 是最容易掉进去的坑。Figma 文件一旦涉及组件库、变体和自动布局原始 JSON 会非常深。直接返回给模型Lightweight 一点的模型可能直接忽略关键内容强的模型也会在无关信息上浪费大量上下文。更合理的做法是把“取数”和“格式化”分开。最小闭环我建议只做三步第一步获取文件基本信息。返回文件名、最后修改时间、顶层画布和画板列表。这相当于给 AI 一份目录。第二步按节点读取。AI 选中某个画板后调用工具读取该节点的子节点。Figma API 支持根据节点 ID 查询文件的部分内容比拉全量文件小很多。第三步把节点格式化成文本。不直接返回原始 JSON而是转成容易理解的结构类似“Frame: 登录页下面有 Input、Button、Text”这样的描述。等这三步稳定了再增加读取样式变量、导出图片、批量读取多个 frame 等功能。2.3 服务端和客户端的边界怎么划MCP 项目里通常有两个角色MCP 服务端和 MCP 客户端。服务端负责注册工具、调用 Figma API、清洗数据、格式化输出、做缓存和处理错误。客户端负责和模型交互把服务端暴露的工具展示给模型并把模型选择的调用结果放回上下文。我一开始容易犯的错误是觉得客户端什么都能做于是把很多逻辑都堆在客户端配置里。后来发现客户端环境差异很大有的客户端支持环境变量有的支持 MCP 配置文件有的连高级参数都暴露不全。更稳妥的做法是服务端把所有逻辑封装好客户端只负责“启动服务”和“发现工具”。简单说能放在服务端的逻辑就不要放客户端。这样换客户端时服务器代码不用动成本低很多。3. 搭建一个可用版 Figma MCP Server3.1 前置条件账号、访问令牌、文件和运行环境先准备四样东西。第一能访问目标 Figma 文件的账号。如果文件属于团队账号至少要具备该文件的查看或编辑权限。权限不足时调用接口会返回 403。第二Figma 个人访问令牌。在 Figma 账号设置里可以生成。生成时要注意存储安全不要提交到 Git 仓库更不要写死在客户端配置里。第三文件的 file key。打开 Figma 文件URL 里/file/后面那段就是https://www.figma.com/file/abcdef123456/项目名称这里abcdef123456就是 file key。第四本地运行环境。服务器一般用 Node.js 或 Python 写。只要能跑 MCP SDK 和一个 HTTP 客户端就行。学习阶段用本地命令行跑内存占用很低生产环境再考虑容器或云端部署。如果你用的是社区现成的 open figma mcp安装和配置会快很多。但自建的优势是可以按自己的设计规范裁剪字段例如只输出自己团队常用的颜色 token、字体层级和间距变量。3.2 最小服务端实现思路MCP SDK 在很多语言里都有核心概念是注册工具。下面是一段非常简化的 Python 示意重点看“把 Figma API 调用包成 MCP 工具”这件事。# 最小示意不以某个具体 SDK 版本为准 from mcp.server import Server, Tool def format_frame(raw, file_key): # 省略从原始节点里提取 name/type/coordinate/size/text/style lines [] for node in raw.get(children, []): lines.append(f{node.get(type)}: {node.get(name)}) return \n.join(lines) def register_figma_tools(server: Server): server.tool( nameget_figma_frame, description读取 Figma 文件中指定画板的子节点结构, parameters{ file_key: {type: string, description: Figma 文件 key}, frame_id: {type: string, description: 画板节点 ID} } ) def get_figma_frame(file_key: str, frame_id: str) - str: raw figma_client.get_nodes(file_key, frame_id) if not raw: return 未找到节点确认 file_key 和 frame_id 是否正确 return format_frame(raw, file_key)真实项目里还要加上对 Figma API 返回异常的处理。对超大节点的截断。日志记录请求耗时和返回大小。缓存设计避免每次调用都打 Figma 接口。这些往往比“注册工具”本身更花时间。3.3 在 MCP 客户端里注册并完成第一轮调用目前主流的 AI 编码工具和部分桌面客户端都已经支持 MCP。不同客户端的配置方式不一样但大体上都支持在配置里声明一个本地命令去启动服务端。常见配置类似这样{ mcpServers: { figma: { command: python, args: [server.py], env: { FIGMA_TOKEN: your_token_here } } } }启动之后客户端会扫描到服务端注册的工具。如果配置成功你在 AI 对话界面里通常能看到get_figma_frame这类函数出现在可用工具列表里。第一轮验证不要搞复杂。直接问 AI读取当前设计稿找出第一个画板叫什么名字里面有哪些子元素。如果 AI 能正确调用工具并返回结果说明整条链路已经通了。如果工具列表里都看不到函数先检查服务端有没有报错再看客户端配置的 command 和 args 是否正确。3.4 缓存、超时和错误返回必须一起处理很多第一次写 MCP 服务的人只关注“接口能不能调通”忽略了缓存和错误设计。但这两个问题直接决定 AI 的实际使用体验。Figma API 对请求频率有控制正式环境不能每次都打全量请求。我通常会在服务端加一层进程内缓存缓存 key 用 file_key 加 node_id再带上文件版本信息。文件变更后缓存要能及时失效否则 AI 读取到的可能是旧设计稿。超时也很重要。Figma 文件大的时候单次节点查询可能很慢。给 HTTP 请求设置合理超时给 MCP 工具调用设置合理超时比让用户等一个永远没有返回的请求要好得多。错误返回要尽量具体。不要直接返回一段 JSON 报错原文。更好的做法是如果是权限问题明确告诉模型“当前 token 没有该文件权限”。如果是节点找不到提示“节点 ID 可能已失效先调用文件信息接口获取最新节点”。如果是超时提示“节点可能过大建议按子节点逐层读取”。模型看到了清晰错误信息才能自己调整调用策略而不是在同一个错误上反复打转。4. 输出设计让 AI 读懂设计稿才是关键4.1 不是把设计数据原样丢给模型Figma API 返回的是完整的文档对象。里面充满了很多模型并不关心的字段插件 ID、内部引用、混合填充数组、各种原始样式对象。把原始 JSON 丢回给模型结果往往是上下文被占满但关键信息没有被表达出来。输出设计的核心是把“设计稿数据”转成“模型容易理解的语言”。我一般会输出类似下面的格式Frame: 登录页 Input: 手机号 type: TEXT_INPUT x: 32 y: 120 width: 336 height: 56 fontSize: 17 placeholder: 请输入手机号 Button: 登录 type: BUTTON x: 32 y: 260 width: 336 height: 48 background: #3478F6 text: 登录这种文本有两个好处。一是模型扫描起来快能快速看到组件的类型、坐标、尺寸和关键样式。二是字段少不容易把上下文消耗在没有意义的细节上。4.2 坐标、尺寸、层级和文本该怎么取舍坐标和尺寸建议都要。AI 生成页面时如果不知道元素之间的位置关系很难还原布局。但要注意直接输出绝对像素不一定利于生成。很多设计稿用的是自动布局父容器的布局方式比单个元素的绝对位置更重要。所以我在输出里不仅给坐标还会标注节点是否属于某个自动布局容器。如果模型发现自己在一个自动布局容器里就会优先用布局属性而不是硬编码绝对坐标。文本内容也值得单独处理。设计师命名的图层名称往往比“Rectangle 1”更有语义。比如图层名是“phone-input”AI 就知道这是一个手机号输入框。输出时要把节点名称保留不要只输出类型。样式字段要克制。常见的输出字段可以是组件类型节点名称坐标和尺寸是否可见文本内容与字号字重背景色圆角是否在自动布局容器内不要输出每一个样式对象的完整字段。模型判断页面风格靠几个关键参数就够了多了反而干扰。另外如果设计稿使用了变量或样式 token优先输出 token 名。比如背景色输出brand/primary就比输出#3478F6更有利于生成代码时复用主题变量。这个在真实项目中价值很大可以放到第二版再做。4.3 用几个“设计稿提问”验证可用性服务器做出来后怎么判断输出设计得好不好我的方法是拿几个固定问题去问模型看它能不能准确回答。适合用来自检的问题包括“这个页面的主按钮在哪里尺寸和颜色是什么”“输入框的 placeholder 是什么”“顶部导航栏有哪些菜单项”“当前 frame 使用了自动布局吗”“这个按钮下面有没有间距异常”如果模型能准确回答说明输出结构合格。如果回答容易混淆就去检查格式化文本里是不是缺了某个字段或者字段名称不够直观。这一步很值得花时间。输出格式是 MCP 服务器和模型之间的接口格式烂后面所有工具能力都会打折。5. 踩坑记录先看日志再改参数5.1 常见报错和排查顺序我在实际调试中遇到最多的问题不是模型能力而是服务端链路里的各种“小毛病”。遇到问题时我一般按下面的顺序查先看现象。工具列表里有没有函数调用后有没有返回返回是空还是报错再看输入。file_key 是不是复数了节点 ID 是不是过期了设计稿里是否存在该节点再看环境。Python 或 Node 版本、依赖版本、token 是否已正确放到环境变量。再看参数。超时时间、缓存命中、输出截断、并发次数。最后看工具逻辑。是不是只支持了部分节点类型比如遇到 COMPONENT_SET 或者 VARIANT 就直接返回空。先说最容易犯的错把 Figma 文件 URL 里的整个链接当成 file_key 用。正确做法是只取/file/后面的那一段。其次容易犯的错是从设计稿界面复制了某个对象链接结果拿到的是带node-id...的 URL而不是普通文件 key。下面这张表是我常用的排查切入点现象优先排查调用返回 403token 权限、文件访问权限返回 404file_key 错误、节点 ID 过期返回空内容节点类型不支持、图层被隐藏、输出格式化逻辑遗漏调用超时一次读取节点过多、Figma API 响应慢、输出内容过大工具列表里没有函数服务端启动失败、客户端配置 command 不对5.2 权限、节点编号和文件体积的真实影响权限问题看起来简单实际很坑。同一个 token可能对某个团队文件有权限换一个外部协作文件就会 403。因为对方文件可能是严格限制访问的即使 token 有效也没权限读取。节点编号也容易踩坑。Figma 节点 ID 一般是类似123:456的字符串。如果从 URL 里复制时带上了其他参数或者经过转码后冒号变成了%3A服务端解析不到就会返回节点不存在。文件体积的影响主要体现在两个地方一是 Figma API 响应时间。大文件、深层级、多组件实例的节点单次查询可能非常慢。不要假设读取一个 frame 就一定会快速返回。此时要做超时和分页或按子节点逐层读取。二是模型上下文占用。如果一个 frame 下有一百多个节点所有节点完整输出可能上千行。模型会把大量上下文花在读无关元素上。我的做法是默认只返回节点名称和类型列表只有当模型要求查看某个具体子节点时才返回更详细的样式和文本信息。5.3 真正卡住项目的往往不是服务器功能踩了这么多坑之后我发现真正影响项目推进的往往不是 MCP 服务器的功能不够强而是你没法假设所有设计稿都是规范的。有的设计稿图层名全叫“Frame 1”“Frame 2”。模型即使拿到了节点也很难理解哪个是标题、哪个是按钮。这种时候光靠 MCP 读节点信息是不够的还要靠上下文里的用户指令去补充语义。还有的设计稿用了大量外部字体。设计端没有安装对应字体时界面里可能显示方框但这不影响 MCP 读取文本字符串。反过来如果读取出的文本为空也不要急着怀疑字体先检查图层类型是不是真正的 TEXT 节点或者文本是不是被设计师做成了图片。我自己还遇到过一个很常见的问题模型能拿到节点数据但不会用。后来发现是因为工具描述写得太模糊。模型不知道一个工具返回的文本适合用来生成代码还是适合用来做设计审查。工具描述里要写清楚返回内容、适用场景和使用顺序。6. 再往前一步从读取到标注、生成和批量接入6.1 可扩展的几个方向第一版跑通后可以考虑扩展这些方向读取样式变量和 design token输出主题变量名。导出节点图片并把图片 URL 返回给多模态模型。读取设计稿评论把评审意见传给 AI。支持一次读取多个画板生成整个页面路由和骨架。把缓存从进程内改成持久化存储方便多客户端共用。在文件版本变更后主动触发回调通知 AI 重新拉取最新设计稿。如果团队里已经有设计规范建议优先做样式变量。这一步对代码生成质量提升最明显。比如一个按钮的颜色到底是硬编码的#3478F6还是主题变量里的brand-primary对前端工程的影响非常大。6.2 边界意识哪些情况不要硬塞给 MCPFigma MCP 服务器不是万能的。复杂设计稿的还原、在线协作编辑、版本历史对比、设计评审流程这些不建议硬塞到 MCP 里解决。MCP 更适合的场景是AI 需要按需获取设计稿信息然后基于信息生成代码、排查样式、做设计稿和代码的一致性问题分析。如果任务需要大量交互式操作比如调整图层、修改设计MCP 的“读”的能力就明显不够。另外安全边界也要考虑清楚。Figma token 本质上是文件访问凭证一定要最小化授权。不要把团队所有文件的 key 都配置在客户端里。模型只应该能访问它当前任务真正需要的文件。6.3 复盘值得长期保留的几条经验如果只留几条经验我会留这些先定义“模型需要回答的设计问题”再定义“Figma API 能提供什么”。顺序反了很容易做出一堆没用接口。输出文本比原始 JSON 重要。MCP 服务器不只是 API 代理更是一个为模型定制的内容转换层。缓存和错误信息不能最后补。AI 调用工具的失败率很多不是出在功能缺失而是出在错误返回不明确、缓存失效不及时。不要一次贪多。先支持最常用的 CANVAS、FRAME、TEXT、RECTANGLE、COMPONENT、INSTANCE后面再慢慢扩展。你如果也在做 AI Engineer 相关的设计稿联动项目建议第一步只做一件事让 AI 能读到你指定画板的节点结构和文本。跑通这条链路之后再考虑样式变量、批量处理、图片导出和 CI/CD 集成。“边飞边造引擎”不是冒险而是让服务器永远跟着真实需求长。