Figma MCP Server 这个名字，我在第一次听到的时候其实反应是"又来了个包装过的玩具"。真正上手用了一周之后，我承认之前的判断下早了。它解决了设计协作里一个特别实际的痛点——AI 不再靠截图猜设计意图，而是直接读取 Figma 文件里的结构、样式和标注数据，然后按你的指令去生成代码、做走查或者整理交接文档。这篇文章我会从服务搭建开始，把 token 获取、配置挂载、核心 API 的使用方法、真实项目的落地流程，以及我在各种边界条件下踩过的坑全部梳理一遍，适合正在做设计工具链开发、想给团队引入 AI 辅助流程的开发者阅读。
1. 为什么需要 Figma MCP Server：从"截图猜意图"到"直接读结构"
1.1 传统 AI 辅助设计流程的瓶颈
过去我们想把 Figma 设计稿交给 AI 去生成前端代码，常规操作是先截几张图，把图丢给对话窗口，然后敲一段 Prompt："按照这张图写一个 React 页面"。等结果出来就会发现，AI 对颜色的判断有偏差、间距只能靠肉眼估算、字体大小基本靠猜，更别提它根本不知道设计稿里用的是哪个组件库、哪些样式变量。这背后的原因很简单：截图是位图像素，AI 看到的是"一张图的样子"，而不是"这个文件的数据结构"。它不知道这个按钮的文字字号是 14px 还是 16px，不知道卡片的边距是来自 Constraint 还是 Auto Layout 的 gap，更不知道某个图层的命名是什么。这些信息其实在 Figma 文件里都有，只是以前的工具链没有把这些数据塞给 AI。
1.2 MCP 协议为设计数据打开了一条标准通道
MCP 全称是 Model Context Protocol，你可以把它理解成一个"通用插座"。过去每个 AI 工具都有自己的一套插件接口，开发者要给 Claude 写专属插件、给 Cursor 写另一套集成，维护成本很高。有了 MCP 之后，只要实现一套标准协议，所有兼容 MCP 的客户端都能直接用。Figma MCP Server 做的就是这件事——它把 Figma 的 REST API 封装成了 MCP 服务，让你本地的 AI 客户端可以直接发起"读取某个文件的节点树""获取某个图层的样式""下载某张切图"这类操作，AI 拿到的是结构化数据而不是模糊的图片。我第一次跑通的时候，让 AI 用 Figma 里的真实颜色值生成了一版样式代码，色值完全一致，那一刻才意识到这套东西不是表面功夫。
1.3 服务的整体架构与核心链路
整个链路可以简化为三层：上层是兼容 MCP 的客户端，比如 Claude Desktop、Cursor、各类自研 Agent；中间是 Figma MCP Server，它是一个跑在本地或者服务器上的 Node.js 服务；底层是 Figma 官方 API。客户端发起请求，MCP Server 把请求转换成对 Figma API 的调用，拿到数据后再按 MCP 协议返回给客户端。值得注意的一点是，Figma MCP Server 主要走的是 Figma API 的只读能力，它不会直接在你的设计文件里做破坏性修改，官方对"写操作"的支持也有限，这一点对团队来说反而是件好事，AI 误改设计稿的风险被降到很低。
1.4 这个服务适合谁
如果你只是偶尔想用 AI 处理一张设计图，那直接截图就够了。但如果你是前端开发，希望在拿到设计稿后自动产出带准确色值、字号、间距的样式代码；如果你是设计系统维护者，想让 AI 帮你检查组件是否按规范使用；如果你是做自动化测试的，需要从设计稿里提取断言数据——这类场景才值得花时间配置 Figma MCP Server。它本质上是个工程化工具，不是给普通用户玩的玩具。
2. 搭建与接入：从零跑通 Figma MCP Server
2.1 环境准备，最容易忽略的 Node 版本
Figma MCP Server 官方推荐用 Node.js 18 以上版本运行。我第一次踩的坑就是 Node 版本太低，导致启动服务时直接报错。建议装 Node.js 20 LTS，稳定且对现代依赖支持好。安装之前先检查本地版本：
node -v npm -v如果没有安装或者版本太低，可以用 nvm 管理多版本：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20这里多说一句，如果你和我一样在公司电脑上同时维护多个前端项目，千万不要图省事直接把系统 Node 升级到最新版，用 nvm 切版本能省掉很多兼容性问题。
2.2 获取 Figma Access Token，权限范围决定后续体验
Figma MCP Server 需要你提供一个 Personal Access Token，用它去调用 Figma REST API。这个 token 在 Figma 的 Account Settings 里找到，路径是 Settings -> Security -> Personal access tokens。创建的时候一定要把权限范围看清楚，至少要勾选File content: Read-only，如果你还要读评论和标注，记得把Comment: Read-only也勾上。很多人拿到 token 之后发现 AI 只能读文件列表，读取文件内容全部报 403，十有八九是权限范围没勾够。
生成 token 之后，建议放在环境变量里而不是直接写进配置文件。我在.zshrc里加了一行：
export FIGMA_ACCESS_TOKEN="你的token"这样做的好处有两个：一是不会把 token 在多个配置文件里复制得到处都是，二是后面切换不同 token 的时候只用改环境变量，不用改一堆 JSON。
2.3 在 Claude Desktop 里配置 MCP Server
Claude Desktop 是目前支持 MCP 最成熟的客户端之一。在它的配置文件claude_desktop_config.json里添加 MCP Server 的定义：
{ "mcpServers": { "figma": { "command": "npx", "args": [ "-y", "@figma-dev/mcp-server" ], "env": { "FIGMA_ACCESS_TOKEN": "你的token", "FIGMA_MCP_PORT": "3838" } } } }配置完成后重启 Claude Desktop，如果一切正常，在对话窗口里应该能看到一个锤子图标，点开就是当前会话可用的工具列表。我建议你配置完之后先问一句"你现在能用 Figma 工具吗"，如果回复说不能，多半是服务没起来，或者配置文件路径写错了。
2.4 命令行直接调用，适合自研 Agent 集成
如果你不是用 Claude Desktop，而是想在自己写的 Agent 里调用 Figma MCP Server，可以先手动启动服务：
npx -y @figma-dev/mcp-server服务默认会打印出 MCP 协议的 stdio 信息，方便客户端通过标准输入输出通信。如果你想改成 HTTP 模式，可以用环境变量指定端口。我自己在做一个内部设计走查工具的时候，是通过 MCP SDK 直接连接这个服务的，只要初始化 MCP client 的时候配置好 transport 就行。相比直接请求 Figma REST API，走 MCP 的好处是工具被标准化了，将来换别的 MCP 客户端不用重写对接逻辑。
3. 核心工具能力拆解：AI 到底能从 Figma 拿到什么
3.1 文件与节点的读取能力
Figma MCP Server 最核心的能力是读取文件结构。通过工具调用 Figma API 的/v1/files/{fileKey}接口，可以拿到整个文件的节点树，包括 Frame、Group、Component、Instance 这些类型，以及每个节点的名字、坐标、尺寸、是否可见等元信息。有了这些数据，AI 才能"知道"页面上有什么。我实际测试过一份中等复杂度的界面稿，文件里有 200 多个节点，服务返回的 JSON 结构化和层次都完整，AI 能准确说出"左上角是导航栏，包含三个链接项"，这并不是它看图看出来的，而是数据里真实带着这些信息。
3.2 样式数据提取：色值、字体、间距的准确性
样式读取比文件结构更实用。通过读取节点的 styles 字段，可以获得 fill、stroke、text 等属性，里面带有真实的颜色值、字体名称、字号、字重。这点比设计稿转图片再给 AI 去"目测"精确太多。下面的效果是让 AI 按设计稿生成按钮样式，它返回的 CSS 代码里background-color: #4F46E5和设计稿里填充色完全一致，间距值也跟 Auto Layout 的 gap 保持一致。
在实际项目里，我会让 AI 把整个页面的设计 token 提取出来，整理成 CSS Variables 或者 Tailwind 配置的形式，省去了开发时反复对着设计稿查数值的工夫。AI 的总结能力在这里发挥了很大作用——它不会只丢给你一堆原始 JSON，而是把相近的色值合并、识别出重复使用的间距规律，生成一份更适合代码里用的 token 表。
3.3 图片导出：让 AI 既能读结构又能看图
MCP Server 还支持把指定节点或者整个画布导出成图片。这意味着你可以让 AI 先读设计稿结构，再导出某个组件的截图，自己"看"一下确认理解是否正确。导出走的是 Figma API 的 image 接口，可以设置导出的格式、缩放比例。我常用的组合是：先让 AI 读取节点风格数据，再让它导出该节点为 PNG 图片，把截图和代码一起输出，做视觉回归的时候特别好用。
3.4 评论读取：设计评审进入 AI 流程
如果团队在设计评审环节会直接在 Figma 里留评论，那么 MCP Server 的评论读取能力就能派上用场。它可以获取某个文件或者某个特定节点上的所有评论，包括评论内容、作者、位置信息。我曾尝试让 AI 汇总一组遗留评论，按"样式问题"和"交互问题"分类整理成待办清单，效果不错。作者信息是匿名的，AI 只知道是谁发的，不知道详细身份，这对隐私保护也算友好。
3.5 其他实用工具
常用工具清单里还有搜索功能，可以按名称在文件中搜索特定节点或者组件。这在大文件里很实用——不用手动滚动找某个图层，直接让 AI 搜索定位。组件读取功能可以提取一个组件以及它的变体信息，设计系统维护者可以用这个能力做组件一致性检查。这些能力加在一起，基本覆盖了设计文件能提供的绝大部分有价值信息。
4. 真实项目里的落地流程与 Prompt 设计
4.1 设计交接场景：从设计稿到开发准备文档
最近做了一个网页端改版项目，设计师在 Figma 里完成了新版首页。以前交接要手动整理一份"设计说明"：主色调、字体层级、间距体系、交互状态，每一项都得人肉去设计稿里翻。现在流程变成：把 Figma 文件的 fileKey 交给 AI，让它读取整个页面的节点和样式数据，自动提取设计 token，再生成一份结构化的交接文档，包括颜色、字体、尺寸、组件列表。我拿到的结果基本可以直接作为开发参考，个别细节我会标注"这里有疑问"，但整体效率提升非常明显。这里给一个能直接用的示例 Prompt：
请读取这个 Figma 文件中首页画布的所有节点，提取以下信息： 1. 页面使用的主色、辅色、文字颜色的具体色值 2. 字号层级，从大到小排列，标明用途 3. Auto Layout 中常用的间距值 4. 页面中出现的组件列表及其变体数量 输出格式：先用表格整理，再给出一份适合写入 CSS 的变量定义。4.2 代码生成场景：给 AI 足够上下文才能写出可用的代码
让 AI 生成页面代码，核心难点在于它要知道两个信息：设计稿长什么样，以及代码要落在什么技术栈上。MCP Server 提供了前者，后者需要你在 Prompt 里明确说明。我的经验是 Prompt 不能只写"生成这个页面的代码"，而是要说清楚技术栈、组件库、样式方案，甚至文件目录位置。比如：
请读取这个文件的报表页面节点，按照以下要求生成 React 代码： - 使用 TypeScript + Tailwind CSS - 已有组件库：请优先使用 Button、Card、Table 这些现有组件 - 页面宽度 1440px，间距使用 8px 基数 - 生成的 HTML 结构需要符合可访问性要求通常拿到结果后，前 80% 的样板代码可以直接用，剩下 20% 涉及业务逻辑和数据联调的部分需要自己补。这不比手写快，但省了翻设计稿敲数字的过程，最大的价值是"代码和设计稿的数值一致"。
4.3 设计走查场景：AI 帮你查样式规范偏差
我试过一个很实用的玩法：给 AI 一个设计规范描述，再让它读取实际页面节点的样式，找出不符合规范的地方。比如规范里定义"所有主按钮高度是 40px、圆角 8px"，AI 读取页面里的 Button 节点，发现有某个按钮高度是 42px，它就能指出来，并标注具体位置。这本质上是个规则引擎，但通过 MCP 把数据接进来之后，不用写一次性爬虫脚本，随时可以针对不同页面跑一遍。对维护设计系统的团队来说，这个场景比单纯生成代码的收益更稳定。
5. 我踩过的坑：MCP Server 接入过程中的真实排查链路
5.1 Token 权限不足，403 报错的定位
有一次配置完测试，AI 能搜索到文件列表，但一读取文件内容就报 403。我当时第一反应是 token 写错了，查了一圈发现不是。后来回到 Figma 的 token 设置页面才发现，我只勾了File content: Read-only，但读取评论还需要Comment: Read-only。MCP Server 的多个工具依赖不同的权限范围，缺一个就会在特定调用上报错。此时建议重新生成一个 token 并严格勾选全部只读权限，省得后面排查麻烦。
我自己的排查顺序是：
- 先用浏览器直接访问 Figma REST API，用 token 测试
/v1/me是否返回真实身份信息； - 如果这个接口正常，再测试
/v1/files/{fileKey}； - 如果第二步正常但 MCP 工具依然报错，就去看 MCP Server 的启动日志，通常里面会有详细的错误请求地址和状态码。
5.2 大文件节点树过长导致的内存压力
Figma 的复杂设计文件节点可能有几千个，直接读取整棵节点树返回的 JSON 动辄几 MB。MCP Server 在传输给 AI 客户端时会占用大量内存，轻则响应缓慢，重则进程卡死。这其实是受限于上下文窗口——AI 一次能处理的数据量是有限的，不可能把整个文件都塞进去。解决方案有两个：一个是尽量在 Prompt 里指定只读取某个页面或者某个节点，减少返回数据量；另一个是用搜索工具先定位目标节点，再读取该节点的详细数据。这个思路跟数据库查询一样，尽量先缩小范围再获取详情，别一上来就全表扫描。
5.3 节点 ID 格式导致的定位失败
Figma 的节点 ID 在 URL 里看到的是类似1234:5678的格式，但 MCP 工具在某些调用里需要把冒号转义成1234%3A5678。如果你从 Figma 地址栏直接复制 ID 塞给 AI，它会请求失败。我一开始不知道这个细节，走了不少弯路。正确做法是让 AI 先读取文件树，从树中拿到节点 ID，而不是自己去地址栏复制。这里也提醒一句：很多 MCP Server 内部已经做了转义处理，但如果你在自研脚本里拼接 URL，务必确认一下是否需要对冒号做 URL 编码。
5.4 缓存和实时性的权衡
Figma API 对文件内容有一定程度的缓存机制，修改设计稿后立刻读取，有可能会拿到旧数据。官方文档说的是约 30 秒到几分钟不等的延迟，视并发和缓存状态而定。在走查场景里这个延迟影响不大，但在"改完设计稿马上让 AI 重新生成代码"的场景里，如果你发现返回的和刚才一样，别慌，等一下再重新请求。这也是一个很常见的 "AI 怎么读不到我最新修改" 的原因，问题往往不在 AI，而在接口缓存。
5.5 自客户端启动 MCP Server 的环境变量继承问题
如果你在配置文件里用npx方式启动服务，记得检查启动时是否真的注入了你设置的 token。Claude Desktop 在 macOS 上如果是从 Dock 启动的，读取不到.zshrc里设置的环境变量，这会导致服务启动成功但 token 为空，AI 任何 Figma 操作都报认证失败。解决方案有几种：最简单的做法是在 JSON 配置的env字段里显式写上 token；如果你不想让 token 到处复制，可以在启动前用launchctl setenv设置环境变量，然后重启客户端。
6. 安全边界、协作规范与扩展思路
6.1 Token 的安全管理
Figma Access Token 等同于你账户在 Figma 上的只读权限，任何人拿到它都能读取你有权限访问的所有文件。不要把 token 提交到 Git 仓库，也不要写在带着代码示例的博文里。如果你发现 token 可能泄露，回到 Figma 后台立刻撤销并重新生成。在公司团队里，我建议给每个成员用自己的 token 接入服务，而不是统一用一个人账户的 token，这样审计和追责都方便。另外，MCP Server 本身会以你的身份访问 Figma，如果你离职，token 失效，相关自动化流程也会停，需要在交接文档里明确。
6.2 只读模式的边界，AI 不会乱改设计稿
我在 1.3 提到过 MCP Server 的写操作支持有限，这其实是个安全特性。很多接入 AI 工具的团队最担心的就是 AI 误操作污染设计文件，比如删除图层、改错样式。当前 Figma MCP Server 的主要能力是读取和导出，这意味着它可以作为"信息源"存在，而不是"操作者"。设计团队可以放心地把它接入开发流程，不用害怕 AI 在某次对话里把画布搞乱。当然，如果未来官方推出更完善的写操作，团队还是要从权限和审计两个维度重新评估。
6.3 多人协作时的使用约定
在团队里使用这套服务之前，建议先约定两件事：文件命名规则和节点层级规范。AI 读取数据时对命名很敏感——如果你有个图层叫 "Rectangle 17"，AI 只能告诉开发者"这是 Rectangle 17"；如果你的图层叫 "primary-button-hover" ，AI 就能生成有意义的变量名和代码结构。设计系统的同学可以借此机会推动命名规范化，因为这套工具把"命名质量"变成了实际生产力指标。另一个约定是：共享给 AI 处理的文件建议单独放到一个项目或者标注清晰，别让所有文件都暴露给自动化流程，减少不必要的风险。
6.4 扩展思路：把 MCP Server 接入自己的工具链
我用过一段时间之后，最大的体会是 Figma MCP Server 不是一个独立的终端产品，它更像一个标准组件，可以和别的 MCP Server 串联。比如在一个项目里，同时接入 Figma MCP Server 和代码仓库相关的 MCP Server，那么 AI 就能一边读取设计稿数据，一边读取当前代码文件，理论上更有可能生成与现有代码衔接良好的结果。你可以用自研的 Agent 编排多个 MCP Server，实现"从设计稿到 PR 草稿"的半自动流程。这种组合式的价值，远超单点使用。
6.5 最后的建议
如果你准备在生产环境里常态化使用，我个人的建议是先把非核心场景跑通再逐步扩大，不要一上来就强制性要求所有开发走 AI 生成流程。先找一个小页面，验证服务稳定性、验证输出质量、验证团队接受度。除此之外，记得关注 Figma API 的调用配额和速率限制，高频读取会导致接口短暂不可用。可以写一个简单的指数退避重试逻辑，让 MCP Server 在遇到 429 时自动等待后重试，这种小细节在实际使用中能极大提升稳定性。
最后再分享一个我实际用下来觉得效率提升最明显的技巧：不要每次都重新让 AI 从头读整个文件，而是先通过搜索工具把目标节点定位出来，再只读取指定节点的详情。这个看起来很小的操作，能把单次请求的数据量降一个数量级，响应速度和上下文里的有效信息密度都高很多。工具链已经很成熟了，剩下的就看你的流程设计得顺不顺。
