Figma和MCP放在一起大概是过去一年多设计开发协作里最能提效的组合之一。MCP全称是Model Context Protocol也就是模型上下文协议它给AI工具提供了一个标准化的外部数据访问通道放到Figma场景里就是让AI可以直接“读取”设计稿中的图层、样式、组件信息再自动整理成开发人员真正需要看的开发文档。以前设计师要把设计稿里的尺寸、颜色、字体、间距一点点搬到文档里工程师还要对着设计稿二次核对沟通成本非常高。用Figma MCP自动生成开发文档之后这部分重复劳动完全可以交给AI去做设计师只需要负责把控文档结构和最终输出质量。这篇文章适合三类人看想减少设计交付返工的设计师、每次都要对着设计稿补参数的开发同学以及正在维护设计系统或组件库的团队。如果你手头已经有一个命名还算规范的Figma文件按照这篇文章的流程走一遍大概率当天就能跑通第一版自动文档。我会从环境搭建、工作流配置、文档结构设计、工具选型、常见坑位这几个角度完整聊一遍尽量让你看完就能在自己的项目里直接复现。1. 为什么开发文档不能直接“画”出来1.1 设计稿和开发文档之间的三层信息差很多设计师一开始会有个疑惑设计稿里明明什么都有颜色、字号、间距都在面板上写得清清楚楚为什么还要单独生成开发文档这里有三个层面的原因。第一层是“位置信息”的缺失。设计稿里一个按钮的填充色为#4F46E5、圆角为8px这些在Figma的检查面板里确实能看到但它是散落的。开发人员关心的是这个按钮在页面里处于什么位置、和周围元素间距多少、在不同断点下如何变化。Figma画布天然是“视觉优先”的它不会告诉你组件之间的层级关系和数据流向。第二层是“状态信息”的缺失。一个按钮通常有默认态、悬停态、点击态、禁用态设计稿里往往只画了默认态其他状态要么藏在组件变体里要么根本没有画出来。开发文档需要把这些状态穷举清楚否则工程师只能靠猜。第三层是“代码映射”的缺失。设计稿里的颜色名称叫“Primary/Blue-600”但代码仓库里可能对应的是--color-brand-primary这个CSS变量。如果文档里不建立这层映射关系等于每做一次页面都要重新对齐语义。所以说开发文档本质上是把“视觉语言”翻译成“工程语言”的中间产物。以前这个翻译过程靠人和人沟通现在可以靠AI来完成但前提是我们要把AI“接”进Figma里让AI能看见画布上的真实数据。1.2 MCP如何让AI“看”懂设计稿光给AI一个Figma文件链接是不够的AI没法直接打开网页去读图层。以前常见的做法是把设计稿截图丢给AI让AI“看图写代码”但截图是扁平信息AI读不到图层名、样式变量、约束关系这些隐藏在文件结构里的数据。MCP解决的就是这个问题。它相当于在AI和Figma之间接了一根数据管道。AI客户端会让用户配置一个或多个MCP服务器每个服务器对外暴露一组工具当AI需要读取Figma内容时它会调用MCP服务器上的工具服务器再通过Figma开放的API拿数据把结果返回给AI。整个过程有几个角色MCP Host也就是你正在使用的AI入口比如Claude Desktop、Cursor这类支持MCP的客户端。MCP Server负责和Figma官方API通信的中间服务它会读取Figma文件并转换成结构化的JSON数据。MCP Tool服务器暴露出来的具体能力比如读取文件、读取节点、渲染图片、读取样式等。Figma APIFigma官方提供的HTTP接口MCP服务器底层调用的就是它。对设计师来说不需要理解每一层协议怎么实现只需要知道一点只要配置好MCPAI就能“打开”你指定的Figma文件看到里面的组件树和属性值而不是仅仅看到一张图。1.3 自动生成开发文档的三个层次我在实际使用中会把“Figma MCP自动生成开发文档”这件事拆成三个层次理解的层次不同做的事情也完全不同。第一层是数据读取层。这个层次只解决“拿到信息”的问题。AI通过MCP读取文件里的节点名称、组件实例、样式属性、图片资源得到一堆结构化数据。第二层是语义整理层。拿到原始数据后AI需要理解哪些数据是有意义的然后按照开发团队的规范去组织。比如判断某个颜色是否该抽成全局Token某个间距是否和栅格系统一致某个字体是否和现有字体栈匹配。第三层是文档生成层。AI将整理后的数据输出成Markdown、JSON、Storybook描述或者代码片段甚至可以生成一份带示例截图的设计Token表。很多人一开始只做第一层觉得“我让AI读到了设计稿就是自动化了”其实远远不够。真正的提效发生在第二层和第三层把Figma里的原始数据加工成开发能直接落地的格式。2. 环境准备把Figma MCP工作流串起来2.1 准备工作清单与角色划分开始之前先把需要的“零件”清点一遍。一个Figma账号并且是你希望读取的文件的所有者或协作者需要具备查看权限。一个支持MCP的AI客户端常见的有Claude Desktop、Cursor其他支持MCP配置的AI工具也可以。一个Figma MCP服务器这里可以选用官方或者社区维护的MCP服务包。一个Figma Personal Access Token相当于给MCP服务器开一把访问钥匙。这套流程里MCP服务器是核心枢纽AI客户端是执行者Token是安全凭证Figma文件里的组件结构是数据源。每个角色的职责要分清后面排查问题的时候才不会一头雾水。2.2 创建Figma Personal Access Token生成Token的入口很多人找不到因为它在Figma的个人设置里而不在文件菜单里。具体路径是打开Figma客户端或网页版点击左上角头像进入Settings切换到Security标签页找到Personal access tokens区块点击Generate new token。生成的时候有两件事要特别注意。第一是权限范围。Figma的Personal Access Token支持精确到文件内容权限比如“读取文件内容”和“写入文件内容”。对我们自动生成开发文档这个场景只需要读取权限不需要写权限。我只勾选文件内容只读降低Token泄露时的风险。第二是Token的有效期和保存。Token生成后只会显示一次样式是一串以figd_开头的字符串要立刻复制保存到安全的地方。之前见过有人把Token随手贴在代码仓库里最后被人拿去偷偷拉取整个设计团队的私密文件非常危险。这里有个比较隐蔽的坑旧版Token默认可能是全文件权限如果你很久以前生成过Token现在直接拿到MCP里用可能权限范围过大建议重新生成一个只读Token。2.3 配置MCP server并接入AI客户端不同AI客户端的MCP配置方式大同小异本质上都是让你提供一个JSON配置告诉AI去哪里找到MCP服务器、执行什么命令、带上什么环境变量。拿Claude Desktop举例它的配置文件通常在用户目录下的claude_desktop_config.json里。一个典型的Figma MCP配置长这样{ mcpServers: { figma: { command: npx, args: [-y, figma-developer-mcp, --stdio], env: { FIGMA_API_KEY: figd_你的token } } } }保存配置文件后重启AI客户端在MCP服务器列表里应该就能看到figma这个条目是启用状态。Cursor的做法稍微不一样它把MCP配置做进了设置面板在Settings MCP里可以添加服务器同样需要填入command、args、env这几项。需要注意MCP的连接方式不止stdio一种还有一种SSE方式。上面的配置用的是stdio也就是AI客户端在本地拉起一个Node进程通过标准输入输出和MCP服务器通信。SSE则适合服务器部署的场景比如你希望团队共用一个MCP服务那就需要单独搭建服务端并暴露接口。个人使用和小组使用选stdio就够简单直接。2.4 快速验证让AI读取一个文件节点配置好之后别急着生成完整文档先做一个最基础的验证。复制一个Figma文件链接最好是带节点ID的链接例如这类格式https://www.figma.com/file/文件ID/文件名?node-id1234-5678然后对AI说一句话“请通过MCP读取这个Figma文件链接找到node-id为1234-5678的节点告诉我这个节点包含哪些子元素以及最主要的填充色、字体大小、圆角值。”如果配置成功AI会调用Figma MCP工具拉取文件数据后给你返回一组比较详细的结构化信息。这一步走通说明MCP链路已经没问题接下来才能真正开始设计文档输出流程。3. 自动生成开发文档的完整实操流程3.1 定义文档骨架先想清楚要输出什么很多人让AI生成开发文档时只会说一句“帮我生成文档”结果出来的内容全是流水账根本没法用。问题出在需求没定义清楚。我自己的做法是先把文档骨架固定下来规定每个组件或者每个页面必须包含哪些信息维度。下面这个表可以作为初始模板信息维度说明示例组件名称组件在代码库里的标准命名PrimaryButton使用场景这个组件什么时候用、什么时候不用表单主操作按钮设计属性尺寸、颜色、圆角、字体、阴影等背景色#4F46E5圆角8px布局规则间距、对齐、自适应规则左右内边距16px高度40px交互状态默认、悬停、点击、禁用等悬停背景色变深设计Token映射设计属性对应的代码变量--color-brand-primary代码示例可直接复制的代码片段CSS、Vue、React无障碍说明对比度、可访问性提示文字对比度达到AA定义好骨架之后再把这个模板放进提示词里。可以写在AI系统的项目说明里也可以每次生成文档时贴在对话里。前一种方式更推荐因为AI会记住这个规则后面每次生成都按同一套格式来。3.2 用准确的Figma链接引导AI解析设计稿读取成败的关键很多时候不在AI能力而在链接给得准不准。Figma链接分两种。一种是纯文件链接只有文件ID不带节点ID另一种是带节点ID的定位链接能直接定位到画布上的某个Frame、Component或Page。自动生成开发文档时强烈建议用带节点ID的链接。原因很简单一个大文件里可能有好几个页面、几十个FrameAI读取文件后虽然能看到树形结构但会花很多时间去猜测哪个是你要的组件。如果链接直接定位到节点AI一进来就知道重点看哪里生成速度和质量都会明显提升。获取带节点ID链接的方法是在Figma画布中选中目标图层右键菜单选择Copy link to selection。这样复制出来的链接里就带了node-id参数。给AI的指令也要写得具体一点比如“读取这个Figma文件链接定位到node-id为1234-4567的组件这是一个登录页的提交按钮。请按我们约定好的文档模板生成开发文档重点提取尺寸、颜色、圆角、字体、内边距和悬停态样式。”这里有一个经验MCP读取的是Figma文件的结构化数据图层命名越规范提取越准确。如果你的图层还叫“矩形 132”AI读到的就是“矩形 132”而不是“登录按钮背景”生成的文档自然没法看。所以跑这套流程之前先花点时间把图层命名规范理一理收益远比你想的大。3.3 让AI输出结构化开发文档读取链路通了模板也定义好了接下来让AI真正输出文档。给AI一个完整提示词示例“请根据我提供的Figma文件链接读取node-id为1234-5678的组件输出一个标准开发文档。格式要求先给组件属性表再给CSS代码片段最后给使用注意事项。设计属性如果有对应的全局颜色变量请自动映射成CSS变量名。”AI通常会很配合地生成这样的结果属性值组件路径components/Button/Primary尺寸宽度自适应高度40px背景色#4F46E5圆角8px字体Inter Medium 14px颜色#FFFFFF内边距左右16px上下10px阴影0 2px 4px rgba(0, 0, 0, 0.1).primary-button { display: inline-flex; align-items: center; justify-content: center; height: 40px; padding: 10px 16px; background: var(--color-brand-primary); color: #ffffff; font: 500 14px/20px Inter, sans-serif; border-radius: 8px; border: none; box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); cursor: pointer; }这里要提醒一句AI生成的内容是“初稿”不是“终稿”。它读到的Figma数据和真实代码仓库里的设计Token不一定完全一致尤其当一个变量在仓库里有多个别名时AI可能选错。所以每次生成完至少要检查一遍组件名、颜色变量、间距单位这三项确认和代码库规范一致后再入库。3.4 从“单组件截图”到“全库设计Token”的进阶用法单个组件文档跑通后就可以把范围扩大了。Figma MCP的价值不在生成一个组件的文档而在批量处理整套设计系统。你可以让AI扫描整个Figma文件里的所有颜色样式、文本样式、效果样式然后汇总成一张全局Token表。举例来说“请读取这个Figma文件的所有本地样式按类型整理成表格颜色样式列出名称、色值、对应的CSS变量名建议文本样式列出名称、字号、字重、行高。”这个操作非常适合设计系统初始化阶段设计师只需要把样式在Figma里定义好AI就能基于MCP读取的数据自动生成一份可用于前端工程的Token初始文件省掉大量手工搬运。另一个进阶用法是生成组件属性对照表。很多团队的组件库有几十个组件每个组件又有多个属性和状态靠人眼去看一遍再整理至少要半天时间。用MCP辅助先扫描文件里的组件列表再逐个读取关键属性最后汇总成一张大表整个流程压缩到十几分钟。4. Figma相关MCP服务器怎么选4.1 几种主流Figma MCP服务器的差异市面上能用的Figma MCP服务器并不止一个形态和侧重点也不太一样。从我和同行交流以及实际试用的感受来看大致有三类。第一类是直接封装Figma官方API的MCP服务器。这类工具会把Figma API的能力平移到MCP工具里比如读取文件、读取节点、渲染图片、获取评论、读取样式等。好处是能力全面和Figma官方接口对齐坏处是返回的数据比较“原始”需要AI做额外整理。第二类是偏向上下文理解的MCP服务器像社区里比较活跃的Figma Context MCP项目。它不光读取原始数据还会对页面结构、组件关系做一定程度的语义分析生成的结果更像“给AI看的上下文”而不是一堆零散JSON。这类工具对组件文档生成更友好但配置和数据格式需要看具体的项目文档来确认。第三类是面向中文开发团队的协作平台MCP比如蓝湖MCP。如果你的团队已经在用蓝湖管理设计交付那它可以作为Figma的设计数据源把蓝湖里的标注、切图、版本记录接进来。好处是符合国内团队的既有工作流坏处是数据源绑定了平台不一定适合所有团队。下面用一张表把差异整理一下类型数据源适合场景注意事项Figma官方API封装型MCPFigma文件直接读取需要完整原始数据自行整理得到的数据结构较原始上下文理解型MCPFigma文件二次加工组件文档、语义化上下文生成项目活跃度影响稳定性设计协作平台MCP蓝湖等平台国内团队已有平台依赖绑定具体平台4.2 选型建议照着团队现状匹配选哪一类建议先看三件事。第一件是设计文件是否高度规范化。如果你的Figma文件里组件命名统一、样式都归集到Variables那选第一类或第二类都能有不错的效果。反过来如果文件还很乱图层名都是默认的“Frame 323”那再强的MCP也救不了先想办法规范文件结构更实际。第二件是团队是否已经依赖某个设计交付平台。已经在用蓝湖管理切图和标注的团队完全可以在MCP配置里加一个蓝湖MCP把Figma MCP和蓝湖MCP结合起来用。Figma负责拿源数据蓝湖负责拿业务上下文两边互补。第三件是AI客户端本身的兼容性。同一个MCP服务器在不同AI客户端里的表现可能有细微差异建议先在本地最小化验证一个文件节点确认正常后再放大范围。4.3 什么时候别用MCP自动生成这条放在这里有点泼冷水但我觉得很重要。当你的设计文件处于高频变动期比如一个页面今天还在大改明天又要换布局这时候建MCP文档意义不大。文档生成一次设计稿一改文档立刻过时反而增加维护负担。另外如果设计稿非常庞大比如一个文件里有几百个页面、上千个组件MCP读取和AI处理的时间会明显变长甚至可能触碰Figma API的调用限制。这种情况下建议按模块分批生成文档不要试图一次处理整个文件。如果设计稿里大量使用了图片素材而非矢量组件MCP能读到的有效属性就很少生成的文档价值很有限。图片类素材更适合走资源管理流程不太适合做结构化文档。5. 踩坑记录与排查技巧5.1 常见报错对照速查表配置和使用Figma MCP的过程中有一批问题属于高频出现的。我把见过最多的几类整理成一张表方便你直接对照排查。报错信息或现象可能原因排查方向404 Not Found文件ID错误或链接指向已被删除的文件确认Figma链接有效检查是否有权限403 ForbiddenToken权限不足重新生成Token勾选文件内容读取权限File not found文件未分享给Token所属账号在Figma中把文件权限开放给相应成员Node not found节点ID失效或图层被删除合并重新复制组件链接Rate limit exceeded请求次数过多放慢请求频率分批读取连接失败或超时MCP服务器版本与客户端不兼容更新MCP服务器依赖重启AI客户端这张表只是起点实际报错信息往往不会写得这么直白。更多时候你看到的是AI那边返回一大段JSON错误关键信息藏在error字段里。我建议遇到问题先做两件事一是检查Figma链接能不能在浏览器里正常打开二是确认Token持有账号在文件里的可见权限。这两步能解决大部分问题。5.2 我实际踩过的五个坑第一个坑是Token权限勾少了。最开始我生成Token时只勾了基础权限没勾文件内容读取权限MCP调用直接返回403。排查了很久才发现是权限范围的问题重新生成Token后才解决。第二个坑是用错了链接。有段时间我直接复制浏览器地址栏里的Figma链接给AI那个链接不带node-id结果AI每次都要先扫描整个文件结构再猜测我要的是哪个区域读出来的内容经常乱套。后来改成用Figma里的Copy link to selection准确率一下子高了很多。第三个坑是命名规范问题。某个页面的按钮背景图层叫“Rectangle 26”没有语义命名AI生成文档时只能写“使用一个矩形作为背景”根本没法用。后来我花了一个小时把组件内的关键图层都改成有意义的名称再读一遍文档质量天差地别。第四个坑是超大文件的处理。我试过一次性让AI读取APP内所有页面并生成一份完整设计规范结果跑了一轮就触发了接口频率限制MCP返回一堆Rate limit error。后来改成按模块分多次读取每次只处理一个页面或一个组件集问题再没出现。第五个坑是版本兼容。某次升级AI客户端之后原来能用的Figma MCP突然失效控制台提示MCP server启动失败。最后发现是npx拉取的MCP包版本和客户端不兼容清理缓存后重新安装问题才解决。5.3 给新手的落地起步步骤如果你想在团队里安全落地这套工作流我的建议是不要一次性铺开。先选一个组件或者一个简单的页面组件按下面的步骤走一遍。第一步把Figma文件里的这个组件完整检查一遍确认图层命名、样式归属、变体状态都正常。第二步配置Figma MCP用只读Token通过AI客户端连接成功。第三步让AI读取这个组件按前面提到的文档模板生成一版开发文档。第四步拿这版文档和人工整理的旧文档对比看看哪些字段有用哪些字段多余记下来调整模板。第五步把调整后的模板固化到AI客户端的项目规则里让后续所有生成任务都沿用同一套标准。这五步看起来简单但很多人第一步和第四步做得不仔细。尤其第四步如果不在初期就认真对比人工和自动的差异后期批量生成时问题会成倍放大。5.4 团队协作里的另外两个隐藏技巧我们team在跑通基础流程之后又摸索出两个比较实用的隐藏技巧这里一起分享出来。第一个技巧是给每个Figma文件强制约定一个“文档入口页面”。在这个页面里放一张画布写上文件说明、组件索引、版本更新记录。MCP读取文件时AI会自动先看到这个入口页面能快速理解整个文件的内容组织方式生成文档时方向感会强非常多。第二个技巧是让AI维护一份“生成日志”。每次自动生成完文档让AI在对话结尾追加一行记录内容包括生成时间、读取的Figma文件ID、生成方式、文档版本号。这样坚持一段时间后你手里会多出一份完整的文档维护日志对排查问题和追责都很有帮助。这两个技巧不需要改代码也不需要额外配置纯粹是使用层面上的经验。我在真实工作中最大的感受是Figma MCP自动生成开发文档这件事工具链本身已经比较成熟了真正的门槛在于把文件结构理清楚、把文档模板定明白、把流程固化下来。工具只是帮你把重复劳动时间挤出来能不能真正提效还是要看使用者的流程设计能力。建议你先从手头最常用的一两个组件开始把这个流程完整跑一遍再慢慢扩大范围。等你习惯了这种工作方式回头再看以前那份几十页、手动维护的组件文档多半就不想再碰了。