Figma MCP 实战：从设计稿到开发文档的自动化生成指南

刚把一版设计稿交付给开发，对方连发了五个问题：“这个按钮的 hover 色值是多少？”“两栏间距是 24 还是 32？”“图标是用 SVG 还是切图？”“小屏下的断点怎么处理？”“组件在 Figma 里的名字叫什么，我这边命名对不上。”说实话，这些问题在设计稿里全都能找到答案，但它们散落在 Figma 的各个图层、样式面板和 Auto Layout 属性里，靠人肉翻找再复制粘贴，一个下午就没了。这也是为什么我今年开始重度使用Figma MCP来做设计交付——它能让 AI 直接读取 Figma 设计文件的内容，自动整理出开发需要的颜色、字体、间距、组件结构，甚至生成可参考的代码片段。这篇文章就把我这几个月踩过的路、验证过的配置方式、能直接抄的提示词模板，还有那些普通教程里不会写的“隐藏技巧”完整梳理一遍。

我默认你是用过 Figma、听说过 MCP，但还没真正把它跑通的设计师或者前端开发。如果你连 MCP 是什么都还不太清楚，也不用担心，第一章节我会用最直白的方式解释清楚，然后再带你一步步把自动生成开发文档的流程搭起来。

1. 先把概念讲清楚：Figma MCP 到底是什么，以及它为什么能用来写开发文档

1.1 MCP 是什么，一句话解释

MCP 的全称是 Model Context Protocol，翻译过来就是“模型上下文协议”。你可以把它理解成 AI 应用的一个万能转接头——以前 AI 只能看你复制粘贴给它的文字，有了 MCP 之后，AI 可以通过一套标准协议去调用外部工具和数据源，实时拿到它需要的信息。

打个比方：如果 AI 是一个新来的实习生，以前你给他需求，得把资料打印好放在桌上他才能开始干活；而有了 MCP，他等于拿到了公司所有内部系统的只读账号，需要什么资料自己查，查完直接出活。Figma MCP 就是这个“内部系统账号”里专门对接 Figma 的那一个，它把 Figma 设计文件中的图层结构、样式变量、组件属性、画板尺寸等信息，通过标准化的方式暴露给 AI 读取。

现在市面上主流的 AI 客户端，像 Claude Desktop、Cursor、Codex、Cherry Studio 等，都已经支持配置 MCP Server。你只需要把 Figma MCP 作为服务挂上去，AI 就具备了“看懂设计稿”的能力。

1.2 在“设计交付开发文档”场景下解决了什么

传统的设计交付流程，本质上是一个“信息搬运”的过程：设计师把 Figma 里的尺寸、颜色、圆角、字体一个个抄到文档里，或者截图标注后扔给开发。这个过程有三个很明显的问题：

第一是慢。一套 20 个组件的设计系统，光整理色板和字体规范就能花掉一两个小时，更别说还要逐个组件填状态、写尺寸说明。

第二是容易出错。人工搬运必然有漏项，尤其是那些“看起来差不多其实差很多”的灰色、圆角值，手一抖就写错了。

第三是信息损耗。设计师脑子里清楚“这个颜色用变量 primaryToken”，但写文档时可能只写了一个十六进制色值，开发拿到的信息和设计稿之间的关联就断了。

Figma MCP 解决的是“让机器直接读机器文件”的问题。AI 通过 MCP 读取的是 Figma 的文件结构本身——哪些是组件、用的是什么样式变量、Auto Layout 里 padding 是多少、constraints 怎么设置——这些结构化信息直接进入 AI 的上下文，再被整理成开发文档。整个过程不需要设计师手动截图、填表、抄数值，准确率也比人肉搬运高得多。

1.3 适合谁、不适合谁

先说说适合谁。如果你是以下三类人，Figma MCP 非常值得试：

• 需要高频给前端、客户端、小程序团队交付设计稿的 UI 设计师，尤其是设计系统维护者。
• 有一定代码理解能力、希望用 AI 提效但不想一头扎进前端工程化的设计师。
• 前端开发，经常需要从设计稿里手动抠参数、希望自动拿规范的人。

再说不适合谁。如果你完全零代码基础，连 JSON 配置、终端命令都不太想碰，那第一次配置 MCP 可能还是会有点门槛，建议找团队里的开发帮你搭一次环境，之后日常使用其实并不需要碰代码。另外一个不适合的场景是超大设计文件——如果一份 Figma 文件里塞了几百个画板、上千个 Frame，直接让 AI 全量读取既慢又容易超 token，这种情况需要拆文件或者指定节点去读，后面我会讲怎么处理。

2. 配置 Figma MCP 之前，先搞清楚这 3 个前置条件

2.1 准备 Figma 个人访问令牌的正确姿势

Figma MCP 要读取你的设计文件，需要一个访问令牌（Token）。获取入口在 Figma 网页版的右上角头像菜单里：点击头像 -> Settings -> Security -> Personal access tokens -> Generate new token。

生成的时候会让你选权限范围，务必注意：只需要勾选File content: read-only就足够了，MCP 读取设计稿只需要只读权限，不要为了省事直接勾 All，权限越小越安全。生成之后，你会拿到一串以figd_开头的字符串，这就是你的 Token。

关于 Token 有几点要特别注意：

• Token 只显示一次，关掉页面之后就再也看不到了，一定要先复制保存好，丢失了只能重新生成。
• 不要把 Token 截图发到群里、不要提交到 Git 仓库、更不要写死在分享出去的配置里。它就相当于你 Figma 账号的钥匙，丢了等于别人能读你的设计文件。
• 如果怀疑 Token 泄露，去同一个页面点 Revoke 作废，然后重新生成一个。

我在实际配置中，习惯把 Token 放在 MCP Server 的环境变量里，而不是直接写进命令参数，这样配置文件和代码库分离，相对安全一些。

2.2 安装 Figma MCP Server，并让 AI 客户端指向它

目前常用的 Figma MCP Server 主要有两个来源：Figma 官方出的figma-developer-mcp，以及社区维护的一些版本。我比较推荐直接用官方的，更新及时、接口稳定，也是我用下来最省心的。

官方安装文档里提供了几种运行方式：npx、uvx、Docker。对于大多数普通用户，我建议直接用 npx，因为它只需要 Node.js 环境，不用另外装 Python 或者 Docker。

以 Claude Desktop 为例，配置文件通常在这个位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

在这个 JSON 文件里添加如下内容：

{ "mcpServers": { "figma": { "command": "npx", "args": ["-y", "figma-developer-mcp", "--stdio"], "env": { "FIGMA_API_KEY": "figd_你的token" } } } }

配置好之后重启 Claude Desktop，在对话里输入“看看我的 Figma 文件”，AI 如果能调起 MCP 工具，就说明连接成功了。Cursor 的配置方式类似，只是配置入口在 Cursor 的 MCP 设置面板里，可以直接通过图形界面添加，然后填入同样的命令和环境变量。

Codex 的情况稍微有点不一样，它支持通过命令行添加 MCP，比如：

codex mcp add figma -- npx -y figma-developer-mcp --stdio

添加之后还需要把FIGMA_API_KEY设置到环境变量里，再重启 Codex 会话，才能被识别到。

2.3 Token 权限范围与文件 ID 获取方式

经常有人问我“为什么我已经配好了 MCP 但 AI 还是读不到文件”，十有八九是文件 ID 或者分享权限出了问题。

先看怎么拿文件 ID。打开任何一个 Figma 设计文件，看浏览器地址栏：

https://www.figma.com/design/AbC123xYz/项目名称?node-id=123-456

其中design/后面、/项目名称前面的那一串字符，也就是上面示例里的AbC123xYz，就是 file key，也就是我们说的文件 ID。如果你的 URL 里有?node-id=123-456，那123-456就是具体节点 ID，可以用它精确定位到某一个画板或 Frame。

再注意一个很多人忽视的问题：即使你的 Token 权限正确，如果 Figma 文件本身的分享权限没有开放给该账号，API 也读不到。Figma 文件至少要对你的账号开放 Viewer 以上权限，建议直接用你登录 Figma 的账号，打开文件后确认右上角能看到文件内容，而不是“需要访问权限”的提示页。

3. 核心实操：用 Figma MCP 自动生成开发文档的完整流程

3.1 第一步：让 MCP 读取设计稿结构

配置完成之后，最激动人心的时刻就是把设计稿交给 AI。这里我给你的建议是：不要一上来就丢一个超复杂的指令，先让 AI 读一遍文件结构，确认它能看懂。

我用 Claude Desktop 时的第一句指令很简单：

请读取这个 Figma 文件，file key 是 AbC123xYz，先帮我把里面的页面和画板结构列出来，不要展开细节。

AI 会调用 MCP 里的工具去拉取文件信息，然后返回类似这样的内容：

• 页面列表：首页、详情页、个人中心
• 每个页面下的画板名称和数量
• 是否使用了组件库、样式变量等

这一步非常关键，原因有三：第一，确认 MCP 工具确实测通了；第二，让你快速了解文件全貌，决定后续是整文件处理还是按节点处理；第三，给 AI 一个“建立地图”的过程，后续让它深挖某个具体画板时，它不会迷路。

如果你只要某一个页面的内容，可以在指令里带上前置的 node-id，让 AI 只读取指定节点，效率会高很多，结果也更干净。

3.2 第二步：提取样式变量与组件规范

结构读完之后，就可以进入正题了。让 AI 深入读取设计稿中的样式信息，包括颜色、字体、间距、圆角、阴影等。我用的指令大概是这样的：

继续分析这个文件里所有画板，提取以下信息： 1. 所有颜色填充的色值，如果有命名样式，优先使用样式名作为颜色标签； 2. 所有文本节点的字体、字号、行高、字重； 3. Frame 的 padding、gap、cornerRadius 值，整理出常用的间距和圆角规范； 4. 组件实例的列表，标注组件名称和使用的变体属性。

我自己实测的案例：一个包含 14 个组件的后台管理页面设计稿，AI 用了大约 2 分钟就整理出了 27 个颜色、4 套字体排版、12 个圆角数值，还自动标注了哪些颜色使用了设计变量、哪些是硬编码色值。这个信息量，如果让我手工在 Figma 里逐个图层去查，起码要一下午，而且大概率会漏掉几个深色模式下的辅助色。

这里有一个细节可以帮 AI 做得更好：如果你们团队在 Figma 里已经建立了样式变量（Variables），尽量在指令里提醒 AI“优先使用样式变量名”，这样输出的文档里颜色和字体都会带上变量名，开发拿到手可以直接对应到代码里的 Token，而不是看到一串十六进制再自己去映射。

3.3 第三步：自动组装开发文档

信息提取完成之后，才是真正的“文档生成”。这时候你需要给 AI 一个明确的文档结构要求，否则它可能会输出成一段散文式的总结，开发根本没法用。

我的建议是给 AI 一个清晰的任务描述，比如：

基于你刚才读取到的设计稿内容，生成一份 Web 前端开发文档，要求如下： 1. 设计规范部分：色板、字体、间距、圆角、阴影、边框，用表格输出； 2. 页面与组件清单部分：列出所有页面、画板下的组件，标注组件类型和用途； 3. 组件详情部分：每个组件至少包含结构层级、尺寸、状态（默认/hover/禁用等）、样式 Token、可复用的代码建议； 4. 响应式说明部分：标注关键画板使用的约束条件和自适应策略； 5. 交付注意事项：列出开发实现时可能需要和设计再次确认的问题。

AI 生成之后，你可以直接复制到飞书文档、语雀、Notion 或者 GitLab Wiki 里，当作正式交付物发给开发。如果开发用的是 Jira 之类的项目管理工具，也可以直接把 Markdown 粘进去，基本不需要再做排版。

我在实际操作中，一份中等规模页面的开发文档，从读取设计稿到生成终稿，整个流程大约 10 到 15 分钟。对比之前手动截图、标注、填表动辄四五个小时，这个效率差距是非常直观的。

3.4 给 AI 的提示词模板（可以直接抄）

写提示词这件事，我踩过不少坑。最开始我给 AI 的指令太笼统，比如“帮我生成开发文档”，结果它输出的是一堆正确的废话：“这个页面采用了现代化的设计风格，使用了圆角卡片布局……”开发看了想打人。

后来我总结出一套相对稳定的模板，你直接复制改一下就能用：

请扮演一位资深前端开发者，基于下面的 Figma 文件生成一份可直接落地的开发文档。 文件信息： - file key: AbC123xYz - 只需要关注 node-id: 1-234 这个画板 要求： - 按设计系统维度整理：颜色、字体、间距、圆角、阴影、边框； - 每个组件列出：名称、状态、尺寸、结构层级（用缩进表示）、样式 Token、可复用的代码建议； - 导出资源部分，标注建议格式（png/svg/webp）； - 色板和字体规范用表格输出； - 最后单独列一个“开发前需要确认的问题清单”，把设计稿中你觉得语义不明确、可能歧义的地方写清楚。

这个模板的核心在于：给了 AI 一个明确的角色、明确的文件范围、明确的输出格式，并且强制它产出一个“问题清单”。这个“问题清单”特别有用，它会把设计稿里那些开发容易产生歧义的地方提前暴露出来，相当于让 AI 替你把设计走查了一轮。

4. 隐藏技巧：普通教程不会写的 Figma MCP 用法

4.1 直接生成 React/Vue 代码骨架，附带设计标注

生成开发文档只是最基础的操作。Figma MCP 真正让我觉得“值回票价”的用法，是它能辅助生成组件代码骨架。

提示词可以这样写：

读取这个组件的节点信息，输出一个 React + Tailwind 的组件代码骨架： - 保持设计稿中的层级结构； - 颜色、圆角、间距使用设计 Token 变量名； - 标出哪些地方需要根据交互状态做条件渲染； - 不要写业务逻辑，只要结构和样式骨架。

实测下来，因为 AI 能看到设计稿里真实的节点层级、Auto Layout 约束和样式值，生成的代码骨架还原度比我以前“截图丢给 AI”高很多。以前 AI 看图经常会自己发挥，多出一个阴影、少了一个圆角；现在它读到的是结构化的设计数据，基本能做到“有什么输出什么”。

不过我要提醒一句：代码骨架只是骨架，距离可直接上线的代码还有距离，尤其涉及交互逻辑、数据绑定、状态管理的时候，仍然需要开发手工介入。但作为初稿，它已经能帮开发省掉一大半“照着设计稿敲标签”的时间了。

4.2 版本对比，自动识别设计变更

这个用法可能很多人没想到：Figma 文件有版本历史的，MCP 可以通过 API 读取不同版本的内容，让 AI 来做新旧版本对比，自动生成“本次设计变更说明”。

指令大概是这样的：

读取这个文件最近两个版本的页面结构，帮我做对比分析： - 列出新增的组件、删除的组件、被修改的组件； - 对每个修改，简要说明变化点（比如颜色、间距、文案、结构层级）； - 输出一份 Markdown 格式的变更说明文档，适合直接贴在工单/群公告里。

实际用下来，这个功能在迭代速度快的团队里非常香。以前每次设计稿有更新，开发都会在群里问“这次改了啥”“哪几个页面要重新适配”，设计师得一张张截图对比。现在让 AI 读一遍新旧版本，几分钟内就能整理出变更清单，而且因为基于节点名称和属性做 diff，基本不会漏项。

需要注意的是，如果文件特别大，版本对比会消耗比较多的 token，建议只指定关键页面或关键组件做对比，不必全文件跑。

4.3 让 MCP 检查设计稿与代码规范的一致性

很多团队有自己的设计 Token 规范，比如主色是brand-primary、成功色是success、字体层级是text/heading-1之类。问题是设计稿里并不总是严格使用这些规范，偶尔会出现某个地方直接填了一个规范里没有的色值。

这种问题以前只能靠设计评审时人工发现，或者开发提 bug 时才发现。现在可以让 AI 充当“规范审查员”：

第一步，把团队的规范写在提示词里，比如：“我们的色板 Token 只有这些：primary #1677ff，secondary #f5f5f5，danger #ff4d4f……字体规范是……”；

第二步，让 AI 读取设计稿中的实际颜色和字体样式；

第三步，让 AI 输出“不符合规范的清单”，列出设计稿中使用了但规范里不存在的色值、字体组合，以及出现的具体位置。

我试过一次，AI 在一个 30 多页的组件库里找出了 7 处未纳入 Token 的硬编码色值，还标注了这些色值分别在哪个画板的哪个组件出现。设计师拿着这份清单去规范化，比自己单独过一遍文件高效太多了。

4.4 文档自动化工作流：设计稿更新 → 文档自动同步

如果你想更进一步，可以把 Figma MCP 结合脚本来实现“设计稿更新后，开发文档自动同步”的工作流。目前的实现思路大概是这样：

1. 用支持 MCP 调用的编程环境，或者通过命令行直接调用 MCP Server；
2. 定时或监听 Figma 文件的版本变化；
3. 发生更新时，自动读取文件内容，调用 AI 生成开发文档；
4. 把生成的文档推送到团队的文档站点（飞书、语雀、Notion、Confluence）或者直接提交到 Git 仓库的 docs 目录。

这个流程的自动化程度取决于你的实际场景。我目前在团队里跑通的是半自动化版本：Figma 文件有新版本后，由设计师在 AI 客户端里一键触发文档生成，然后复制到公司文档站点。完全自动化的版本需要额外写一些胶水代码，更适合有开发资源的团队去搭建。

做这个工作流有一个前提：设计稿必须足够规整。如果图层命名混乱、页面结构随意，那 AI 生成的文档质量也会随之下降。换句话说，MCP 不会解决脏乱差设计稿的问题，它只会把规整设计稿的交付效率放大。

5. 常见问题与排查技巧实录

5.1 Token 获取不到 / 401 报错

如果你在配置完 MCP 之后，AI 调工具时报 401 Unauthorized，大概率是 Token 的问题。排查顺序如下：

1. 确认 Token 是否以figd_开头，并且完整粘贴到了环境变量里，没有多余空格；
2. 确认生成 Token 时勾选了File content: read-only权限；
3. 确认 Figma 文件对该账号开放了访问权限；
4. 确认你的 AI 客户端在读取环境变量时，确实加载了FIGMA_API_KEY。有些客户端改了配置后必须完全退出重启才生效，不能只刷新窗口。

如果以上都正常仍然 401，最简单的办法就是重新生成一个新 Token，换掉旧的试一试。这个问题我遇到过两次，基本都是 Token 权限勾选少了或者复制时漏了后半段。

5.2 读取不到文件内容 / 文件 ID 错误

AI 能连上 MCP，但回复“找不到文件”或者“文件内容为空”，这种一般不是 MCP 的问题，而是文件 ID 或 node-id 传错了。

注意几个细节：

• file key 是design/和/项目名之间的那一段，别把项目名当成了 key；
• node-id 里的格式可能是123-456，中间是短横线，不是下划线；
• 如果你指定了 node-id，但这个 node 不是一个画板或者 Frame，API 可能会返回空结构。这时候不传 node-id，让 AI 先读文件整体结构。

另外一个冷门但很常见的坑：如果你的设计文件是存在 Team Library 里的组件库项目，而不是普通设计文件，file key 的获取方式是一样的，但读取速度可能会更慢，因为组件库通常图层非常多。建议把组件库文件按需要拆几个文件来管理，或者指定 node 读取。

5.3 MCP Server 连不上 / 客户端识别不到

这种情况通常是 MCP Server 本身没有启动成功。先在终端里单独验证一下：

npx -y figma-developer-mcp --stdio

如果命令能正常运行不报错，说明 MCP Server 本身没问题，问题出在客户端配置上。如果命令直接报错，大概率是 Node.js 环境没装好，或者网络拉取 npm 包失败。

客户端识别不到工具的场景，大部分是配置文件 JSON 格式出错，比如多余逗号、引号不匹配、环境变量路径写错。检查完 JSON 之后，重启客户端，注意是要完全退出进程，不是关闭窗口。Cursor 和 Claude Desktop 在配置变更后都需要彻底重启才会重新加载 MCP Server。

如果你用的是 Codex，可以通过codex mcp list查看当前已经加载的 MCP Server 列表，确认 figma 是否在列表里。如果不在，检查添加命令时的参数，特别是环境变量有没有同步设置。

5.4 AI 生成了看似合理但实际错误的文档，怎么防？

这是我最想强调的一点：MCP 提效不等于无人值守，AI 生成的内容一定要人工抽查。尤其是颜色、圆角、字号这类精确数值，AI 在整理长文档时偶尔会出现错位。

我的防错经验有三条：

第一，限制 AI 的读取范围。如果只需要某个页面的文档，就用 node-id 圈定范围，不要让 AI 读整个文件。读取范围越大，混淆的概率越高。

第二，在提示词里要求 AI 优先使用设计变量名，而不是直接给十六进制色值。变量名本身是语义化的，AI 不太容易搞混，而且开发拿到的信息更接近代码里的 Token 引用。

第三，生成文档后，抽查几个关键值。我习惯重点核对主色、常用文字色、最大的圆角值和默认间距这几个高频参数。如果这几项都对，其他小概率错误影响一般不大。

有一次 AI 把两个非常接近的灰色值搞混了，一个是#f5f5f5，一个是#f0f0f0。如果我没抽查出来，开发照着做出来的页面在暗色背景下会出现不太明显的色差，这种问题在 QA 阶段很难被发现，但在用户面前会很显眼。后来我每次生成完文档，都会把色板表格和 Figma 里的样式面板快速对照一遍，两分钟的事，能避免很多返工。

5.5 常见问题速查表

为了方便你以后快速排查，我把上面提到的问题做成了一个速查表：

最后再分享一点我自己实际使用中的体会

Figma MCP 不是一个能让设计师一夜之间变成全栈开发的神器，它真正解决的是“设计稿信息到开发文档”之间那段低效重复的搬运过程。以前每次交付，设计文档就像一封手写信，要逐字逐句地写清楚；现在更像是在开一个自动化的接口，让 AI 直接从数据源里提取要点。坦率地说，配置 MCP 的第一个下午可能有点折腾，尤其是环境变量、JSON 格式、权限设置这些细碎的东西。但一旦跑通，后面每一次设计交付都能省下大块时间。

如果你想开始尝试，我的建议是从一个小页面、一个组件库子集开始，不要一上来就拿着巨型文件去跑。先让 AI 读一个画板，生成一份十来行的文档，确认输出质量和格式都符合预期，再逐步扩展到更多页面。最后一个小技巧：给 AI 下指令时，尽量把输出格式要求写清楚，比如“用表格输出色板”、“列出问题清单”、“标注哪些是硬编码色值”，这些明确的约束能让生成结果的质量立刻上一个台阶。别问我怎么知道的，都是被一堆“正确的废话”教育出来的。