Figma MCP 实战：自动读取设计稿生成开发文档

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 API，Figma官方提供的HTTP接口，MCP服务器底层调用的就是它。

对设计师来说，不需要理解每一层协议怎么实现，只需要知道一点：只要配置好MCP，AI就能“打开”你指定的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-id=1234-5678

然后对AI说一句话：“请通过MCP读取这个Figma文件链接，找到node-id为1234-5678的节点，告诉我这个节点包含哪些子元素，以及最主要的填充色、字体大小、圆角值。”

如果配置成功，AI会调用Figma MCP工具，拉取文件数据后给你返回一组比较详细的结构化信息。这一步走通，说明MCP链路已经没问题，接下来才能真正开始设计文档输出流程。

3. 自动生成开发文档的完整实操流程

3.1 定义文档骨架：先想清楚要输出什么

很多人让AI生成开发文档时只会说一句“帮我生成文档”，结果出来的内容全是流水账，根本没法用。问题出在需求没定义清楚。

我自己的做法是，先把文档骨架固定下来，规定每个组件或者每个页面必须包含哪些信息维度。下面这个表可以作为初始模板：

定义好骨架之后，再把这个模板放进提示词里。可以写在AI系统的项目说明里，也可以每次生成文档时贴在对话里。前一种方式更推荐，因为AI会记住这个规则，后面每次生成都按同一套格式来。

3.2 用准确的Figma链接引导AI解析

设计稿读取成败的关键，很多时候不在AI能力，而在链接给得准不准。

Figma链接分两种。一种是纯文件链接，只有文件ID，不带节点ID；另一种是带节点ID的定位链接，能直接定位到画布上的某个Frame、Component或Page。自动生成开发文档时，强烈建议用带节点ID的链接。

原因很简单：一个大文件里可能有好几个页面、几十个Frame，AI读取文件后虽然能看到树形结构，但会花很多时间去猜测哪个是你要的组件。如果链接直接定位到节点，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通常会很配合地生成这样的结果：

.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的设计数据源，把蓝湖里的标注、切图、版本记录接进来。好处是符合国内团队的既有工作流，坏处是数据源绑定了平台，不一定适合所有团队。

下面用一张表把差异整理一下：

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的过程中，有一批问题属于高频出现的。我把见过最多的几类整理成一张表，方便你直接对照排查。

这张表只是起点，实际报错信息往往不会写得这么直白。更多时候你看到的是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自动生成开发文档这件事，工具链本身已经比较成熟了，真正的门槛在于把文件结构理清楚、把文档模板定明白、把流程固化下来。工具只是帮你把重复劳动时间挤出来，能不能真正提效，还是要看使用者的流程设计能力。建议你先从手头最常用的一两个组件开始，把这个流程完整跑一遍，再慢慢扩大范围。等你习惯了这种工作方式，回头再看以前那份几十页、手动维护的组件文档，多半就不想再碰了。