1. 设计交付的最后一公里卡在文档上干设计这行久了你一定遇到过这种场景设计稿改了十二版终于定了开发兄弟拿着标注图来问你“这个间距是多少”“这个颜色有没有Token”“交互异常态怎么处理”。你嘴上说着“你看设计稿就行”心里清楚设计稿里很多信息并不能直接变成他们能用的东西。我最初接触Figma MCP就是被这种重复劳动逼的。当时团队里五个设计师共用一个Figma团队库每个迭代要输出组件变更说明、样式更新记录、页面流程逻辑。开发那边希望文档能贴合代码结构最好直接给出变量名、层级关系、关键state。手工整理一份要一整个下午而且下次迭代又得重来。后来在一次技术分享里看到有人用MCPModel Context Protocol模型上下文协议把Figma的设计数据喂给AI让AI自动生成开发文档。试了一周之后我确定这东西不是玩具它真的能把“设计师整理开发文档”这件事从手工劳动变成半自动流水线。这篇就把它拆开聊MCP到底怎么连Figma、token在哪拿、配置完之后能跑哪些场景、以及我实测过程中踩过的坑。标题里说的“隐藏技巧”其实不是什么黑魔法而是把Figma的API能力、MCP协议的数据传输方式、AI模型的文档生成能力拼在一起。但很少有人系统讲清楚这三者怎么配合所以我用实际操作的视角来写。无论你是UI设计师、设计团队负责人还是想帮设计团队提效的前端工程师这篇都能给到可落地的方案。2. MCP不是魔法先理解它为什么能“看懂”设计稿2.1 没有MCP的时候AI只能“看”不能“读”很多人第一次接触Figma MCP会误以为它是Figma官方出的新功能。其实MCP是Anthropic在2024年底开源的一套协议标准全称Model Context Protocol解决的核心问题是让AI模型能安全地调用外部工具、读取外部数据。类比一下你就懂了。你在浏览器里打开Figma网页版和在本地打开一个逐行记录设计数据的JSON文件看到的信息完全不一样。普通用户只能看到画布上的图形但一个结构化的设计文件里其实存着每个节点的名字、坐标、尺寸、填充色、字体、渐变、约束关系、组件嵌套关系——这些才是开发真正需要的东西。没有MCP之前想让AI“读”设计稿常规做法是把设计稿截图发给AI让它“看”图。但图是位图AI靠图像识别能猜个大概却读不出精确的色值、间距、层级。另一个做法是导出JSON再手动粘贴到对话里费劲不说大文件根本塞不进上下文。MCP做的事就是给AI装上一双能“读”结构化数据的手通过这些专属工具按需获取Figma文件里的真实数据而不是靠猜。2.2 Figma的API是地基MCP只是管道这里要澄清一个常见的误区MCP本身不存储任何Figma数据真正干活的是Figma的REST API。MCP Server只是把API的调用封装成一个个语义化的工具让AI知道“哦原来我可以用get_styles来读颜色样式”“可以用get_component_info来查组件信息”。以我目前用的figma-developer-mcp为例它把Figma API封装成了这些核心工具工具名作用对应的开发文档场景get_file_info获取文件基本信息、页面列表文档目录结构get_file_json读取整份文件的结构化数据全局设计Token梳理get_image按节点导出PNG/JPEG/SVG文档配图、标注图get_component_info查询组件属性、实例关系组件API文档get_styles读取颜色、字体、特效样式Design Token清单get_fonts获取字体使用情况字体资源统计也就是说MCP Server相当于一个翻译层。AI发起一个“读样式”的请求MCP Server把它转换成Figma API的HTTP请求拿到JSON数据后再翻译回AI能理解的文本结构。这套链路里Figma API负责权威数据MCP负责规范化调用AI负责理解和生成各司其职。2.3 为什么这套联动比人工整理更可靠我见过不少设计师说“我自己看设计稿写文档也很快啊”。确实小项目手工整理没问题但一旦设计系统上了规模情况就完全不同。手工整理文档的最大问题是“选择性失明”。你面对一个50个页面、2000多个节点的设计文件肉眼能看到的只是当前画布上的内容。藏在组件库里的变体、未被引用但在库里存在的失效样式、嵌套了五层的自动布局——这些靠手工根本顾不过来。而Figma API返回的是全量数据AI基于全量数据生成文档漏项的概率低很多。更重要的是MCP读取的是“数据”而不是“样子”。比如开发要一个按钮组件的颜色Token传统做法是设计师吸色、查变量名、手抄进文档MCP方案里AI直接调用get_styles把整个文件的颜色变量连同名字、值、引用关系一次性拉出来再按要求格式化。数据源头一致就不会出现“文档上写的#2A6CF4和设计稿实际用的#2A6CE4对不上”这种低级事故。3. Token获取到Server配置全流程跑一遍3.1 先去Figma设置里生成Personal Access Token配置Figma MCP的第一步是拿到一把能访问你设计文件的钥匙Figma官方叫Personal Access Token。打开Figma客户端或网页版点击右上角头像进入Settings设置切到Security安全标签页。往下找Personal access tokens一栏点击Generate new token。这里要注意Figma会要求你输入token的名称建议取一个能标识用途的名字比如figma-mcp-design-doc。过期时间可以选7天、30天或自定义本地个人使用就选30天团队长期用建议建一个专门的服务账号。生成之后Figma会展示一次完整的token字符串形如figd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。一定立刻复制保存关掉弹窗之后就再也看不到了。我们团队之前有人没保存就关页面结果只能重新生成旧token作废还排查了半天。关于权限范围如果只是读取设计文件用于生成文档勾选File content: Read-only就够用了。有些人图省事直接把全部权限都勾上这在安全上非常不推荐。因为token会以明文形式写在MCP Server的配置文件里万一配置被分享出去等于把整个团队设计文件的读权限都暴露了。3.2 选一个MCP Client把Server挂上去拿到token之后需要一个“宿主”来运行MCP Server。目前主流的MCP Client有Claude Desktop、Claude Code、Cursor、VS Code的Cline插件等。设计师最常接触的可能是Claude Desktop图形界面友好配置方式也直观。以Claude Desktop为例编辑配置文件claude_desktop_config.json路径一般在macOS~/Library/Application Support/Claude/Windows%APPDATA%\Claude\在配置文件的mcpServers节点里加上Figma的配置{ mcpServers: { figma: { command: npx, args: [ -y, figma-developer-mcp, --stdio ], env: { FIGMA_API_KEY: 你的figd_token } } } }保存之后重启Claude Desktop如果一切正常聊天输入框旁边会出现一个工具图标点开就能看到Figma MCP暴露出的工具列表。如果没出现到Claude的MCP日志里查看启动报错八成是npx没装好或者token格式不对。3.3 用三个信号判断连接是否真的通了MCP配置完成不等于能用。我建议用以下三个信号来确认链路通畅信号一工具列表里能看到figma开头的工具。没有工具列表说明Server没加载成功优先查JSON格式和command路径。信号二直接问AI“请帮我读取文件key为xxxx的文件信息”。如果返回了文件名称、页面列表等真实数据说明token、网络、API权限全通了。如果报401或403说明token无效或权限不足。信号三让AI读取一个已知节点的样式数据比如“读取这个frame节点的背景色”然后和Figma里吸管工具的实测值对比。一致说明整条链路数据无损耗。这三个信号都过了才算真正准备好。很多教程只讲到“能打开工具列表”但工具列表存在只代表Server进程跑起来了不代表Figma API真的能访问。我自己第一次配置时就被这个表象骗了工具列表都在一问AI就说报错最后发现是token的过期时间设成了1天早就失效了。4. 能直接省时间的四个文档自动化场景4.1 组件变更说明从“设计师口述”变成“AI生成对比报告”团队里最高频的文档工作大概是组件库迭代后的变更说明。以前的做法是设计师改完组件在群里所有人“按钮组件的hover色改了disabled透明度改了圆角从8改成10”然后开发自己去diff设计稿。有了Figma MCP之后可以这么做在Figma里拿到文件key和组件节点id让AI调用get_component_info获取当前组件的完整配置再结合你自己提供的上一版配置或者直接让AI读取文件的历史版本信息自动生成结构化的变更说明。我实测的一段Prompt是这样写的请读取文件key为abc123中的组件“Button/Primary”的信息对比我在下方给的上一版配置清单生成一份组件变更说明按“变更属性-旧值-新值-影响范围”四列表格输出。AI会先读取当前组件数据然后和你给的旧版数据对齐最后输出一份开发可以直接照着改的清单。整个过程从原来的半小时压缩到两分钟而且输出的格式整齐开发那边可以直接贴进自己的任务拆解里不需要再手动转一遍。4.2 Design Token清单让样式数据变成代码变量设计系统成熟之后团队一定会沉淀Design Token——颜色、字体、间距、圆角、阴影的统一定义。这些数据散落在Figma的样式面板里导出来是有格式的但Figma自带的导出结果偏设计侧开发还得自己转换成CSS变量或平台代码。用MCP的方式让AI读取get_styles返回的JSON再指定输出格式比如让AI生成一份CSS Variables格式的token文件读取文件key为abc123的全部样式数据按颜色、字体、字号、行高、间距、圆角、阴影分类输出为CSS自定义属性格式命名保持和Figma样式名一一对应并在注释里标注Figma样式原名。AI会拿到原始的样式数据然后按你要求的格式重组。比如Figma里一个叫“Primary/Default”的颜色样式值可能是#2A6CF4AI会输出/* Primary/Default */ --color-primary-default: #2A6CF4;这个过程的含金量在于命名一致性。手工转录的Token清单经常出现开发侧和设计侧命名对不上的问题而AI基于同一份Figma数据生成代码天然保持了对应关系。只要Figma侧的样式命名规范AI生成的代码侧命名就是规范的。4.3 页面逻辑与交互流程说明从节点结构里读出用户路径很多开发拿到高保真设计稿第一反应是“好漂亮然后呢”。光有静态页面看不出交互逻辑这个页面从哪里进来、点击哪里跳转、异常态怎么展示。设计师脑子里很清楚但常常忘了写下来。利用MCP你可以让AI读某个页面的节点结构特别是frame和component的嵌套关系再结合你的描述生成页面逻辑说明。比如一个登录页面AI能读出哪些是输入框、哪个是按钮、有什么校验提示节点你只需要补充跳转规则AI就能生成一份开发可读的交互说明。实操时我会先把页面结构读出来再告诉AI交互路径文件key为abc123请读取页面“Login”的所有frame、component层级结构。我补充三个交互规则1. 点登录按钮校验手机号格式2. 校验失败时显示错误提示组件3. 成功后跳转首页。请结合节点结构生成一份页面逻辑说明文档按“功能模块-触发元素-前置条件-反馈行为-跳转目标”组织。AI返回的文档里会注明“功能模块登录表单触发元素Button/Login节点反馈行为显示Form/Error组件”等等。开发拿到文档再对照Figma里的节点名就可以直接定位代码文件效率提升非常明显。4.4 为Frame节点批量生成开发注释和组件说明最后这个场景是我个人用得最多的。Figma官方有Dev Mode能查看选中元素的代码级属性但它给的是“属性值”不是“说明文字”。比如API会告诉你某个文本节点的字号是16、字重是500但它不会告诉你“这个标题在小屏下要缩到14”。但MCP可以。我通常的做法是先让AI读取组件的完整信息尺寸、约束、变体再针对我额外补充的响应式规则生成一段开发注释。比如读取文件key为abc123中的Card组件信息。该组件在移动端需要隐藏副标题、主图比例改为1:1。请结合读取到的节点属性生成一份含props说明、响应式规则、使用注意的组件开发文档。AI返回的不再是冷冰冰的属性列表而是有上下文的说明文字。这就把“Figma能显示什么”升级成了“开发需要知道什么”。特别是新入职的工程师拿到这样的组件文档基本不需要反复来问设计师。5. 实测中踩过的坑Token、大文件与AI幻觉5.1 Token失效比想象中来得快第一次配置MCP我用的token有效期设了30天结果第25天的时候AI突然开始报“Failed to fetch file data”。当时第一反应是网络问题查了很久才发现是token过期了。这个坑背后有两个教训第一Figma的Personal Access Token过期后不会自动续期必须在设置页面重新生成第二多个环境共用同一个token的话一个环境更新另一个环境可能没同步更新。我们团队后期的做法是单独建一个“MCP服务账号”token有效期拉长并且把token放进一个共享的秘密管理工具里而不是散落在各人的本地配置中。另外要提醒如果你在配置里写了token然后把这个配置文件贴给别人或传到公开仓库等于把你的设计文件权限也交出去了。GitHub上专门有爬虫扫描这种泄露的token别在公开环境贴配置文件。5.2 大文件的JSON会撑爆上下文窗口Figma MCP读取的是全量结构化数据一个几百MB的设计文件其JSON可能超过10万token。直接让AI“读取整份文件”然后生成文档很多模型会直接报上下文超限或者生成到一半开始胡言乱语。我第一次实操时让AI读一个包含全部页面的文件它愣了好一会儿然后输出了一段“文件结构过于复杂我无法完整读取”的提示。后来我调整了策略先读文件信息确认页面列表和节点id再按单个页面、单个组件、单个样式分类去读不贪多分批次生成文档最后用一次对话合并成最终稿这个策略的本质是把MCP当成一个“精准查询工具”而不是“全量搬运工具”。你需要什么数据就让AI去调对应的工具拿对应的节点而不是一上来就要求它理解整份文件。5.3 AI会一本正经地编造样式值这是MCP方案里最需要警惕的坑。AI在生成文档时如果它读取的数据不完整或者它的回答被截断了它会倾向于“脑补”缺失的部分生成看似合理但实际不存在的色值、字号或组件名。有一次我让AI生成一份颜色Token清单它输出的内容格式很漂亮但我核对Figma原始文件时发现其中几个色值在文件里根本不存在完全是AI“猜”的。从那以后我在Prompt里加了一条硬性要求“所有数据必须直接引用Figma读取结果不得推测、补全、猜测任何值数据缺失时标注‘待确认’。”这在专业上叫“降低模型幻觉”。AI生成类任务天然存在这种风险MCP虽然提供了数据源但模型在组织语言时仍有概率产生与数据源不一致的表述。不管是生成文档还是代码最后一定抽样式或关键参数和Figma源文件抽检对比特别是颜色、尺寸这类容易编造的值。5.4 命名混乱的设计文件生成的文档也很混乱MCP只是忠实反映了设计文件的内容它没有能力替你修复命名规范。如果某个组件叫“Frame 137”或者“组 123”那么AI生成的文档里也会出现“Frame 137”这种开发看不懂的名字。这个坑没法靠MCP解决只能靠设计侧规范。用过一阵子之后我反而把它当成一个命名规范检查工具生成的文档里出现大段“Frame xxx”“Group xxx”就说明该整理的图层名称没整理。AI不会抱怨你的命名但文档会诚实地暴露设计文件的管理水平。我给团队的硬性建议是接入MCP自动生成文档之前先花一个迭代的周期把图层命名规范补齐特别是组件名、变体名、样式名。这不仅是配合MCP任何形式的自动化交付都需要一个干净的输入。6. 让AI输出更靠谱Prompt设计的四个关键习惯6.1 给足“上下文”AI才知道你给谁写文档同样的Figma MCP有人生成的文档开发叫好有人生成的文档没人看差距主要出在Prompt上——准确说是给AI的“上下文”不足。裸的Prompt效果读取这个组件的样式生成文档。AI确实会读但它不知道文档是给前端还是后端看的、语言风格要偏代码还是偏自然语言、内容要详还是略。结果生成一份“没有灵魂”的属性堆砌。好的Prompt应该包含四个要素身份、读者、格式、边界。举一个我在生产环境用的例子你是一名资深前端开发工程师现在需要根据Figma数据编写一份组件开发文档读者是团队初级开发。 请读取文件key为abc123中的组件“Button/Primary”结合组件属性、变体列表和样式Token输出一份Markdown文档包含组件功能简介一至两句话props表格属性名对应Figma节点名类型参考常见TS类型样式Token引用与文件中的变量名一致变体说明列出所有变体及其差异使用注意事项基于节点结构中的约束和自动布局信息。 注意所有字段值必须来自读取结果不要推测。读取结果中不存在的值标为“待确认”。这样AI知道文风、结构、详细程度也知道数据边界在哪。6.2 分步提取再生成避免一次读太多另一个关键习惯是把“数据获取”和“文档生成”分成两个步骤而不是混合在一条Prompt里。MCP工具调用本身是幂等的但AI的生成质量会受上下文杂乱程度影响。我的做法是第一步先让AI读取数据但不要生成文档只让它总结“我已经读到了哪些结构、有哪几个关键的样式值”并输出成简洁的数据摘要。第二步基于摘要让AI生成文档。由于上一步已经完成了数据归纳这一步AI的输出会更聚焦而且即使生成中途出问题也可以基于摘要继续不必重新读一遍Figma。这个流程还能帮你省token——读取一次数据可以复用多轮对话而不是每次生成新文档都重新走一遍MCP调用。6.3 一个可直接复用的模板最后分享一个我实际在用的模板可以直接复制到你的MCP Client里试背景我们是一个Web端设计系统团队每两周一个迭代。每次设计稿评审后需要向开发团队提供一份“设计移交说明”。 任务请读取Figma文件keyxxx中的【首页-搜索结果页-状态页】三个页面以及设计系统库中的Checkbox、Radio、Switch三个组件。 输出要求Markdown格式章节清晰每个组件一节包含属性表、样式Token、变体列表、交互状态、使用说明颜色、字号、间距必须引用文件里的真实Token名新增和变更的Token要单独放在表格里页面部分按“模块-功能点-交互规则-关联组件”四列输出所有信息以MCP读取结果为准缺少的信息标注“待设计补充”不能自行填写。这个模板的好处是把重复性的文档生成行为标准化每次只需要改文件key、页面名、组件名就能生成风格统一的文档。我们团队现在三个设计师都在用这个模板输出格式几乎一致开发那边的阅读成本也降低了。7. 自动化文档不是终点它逼着设计团队把规范建起来最后聊一点个人感受。用Figma MCP自动生成开发文档这件事真正改变的不是“写文档”这个动作本身而是它把设计团队的规范性问题暴露出来了。你没法让AI替你写出一个本来就不存在的语义化命名你没法让AI在一份混乱迭加的文件里找到“真正的”交互流程你没法让AI在页面结构逻辑混乱时给出逻辑清晰的文档。但它能非常高效地把你已有的规范落地成文档并且在输出格式上保持一致。我自己用下来的体会是MCP和AI不会淘汰设计师但会用工具的设计师可以省下大把时间重新放到真正需要判断力的地方——梳理交互逻辑、优化组件边界、推进设计规范。这才是这个“隐藏技巧”最核心的价值。顺便分享一个小建议如果你准备在团队里推广Figma MCP不要急着要求所有人立刻切换工作流。先用一个人的真实项目跑通生成几份文档给开发试用收集反馈再同步到全组。工具本身没有门槛但流程变化需要人适应慢一点反而稳一点。