尧图网页设计 
最近在设计圈和前端圈频繁看到一个组合被讨论Claude Figma MCP。如果你已经尝试过让 AI 帮你写前端代码大概率遇到过AI 写出来的东西跟设计稿完全是两个世界的尴尬。MCP 的出现把让 AI 看图猜设计升级成了让 AI 直接读取设计稿数据这个变化非常实用。这篇教程我会从零开始把 Claude、Figma、MCP 三者的关系讲清楚再一步步带你完成环境配置、连接调试和实战调用期间会穿插我实际踩过的坑和排查经验。无论你是设计师想用 AI 辅助走查还是前端想把设计稿直接转成代码这篇内容都能给你一条直接可走的路径。1. MCP 是什么为什么要把 Claude 和 Figma 连起来1.1 MCP 协议的核心概念与设计思路MCP 全称是 Model Context Protocol直译过来是模型上下文协议。官方定义比较拗口我用一个生活化的类比来讲MCP 就像 AI 世界的 USB-C 接口。以前你给手机充电需要各种品牌专属的充电线换一个设备就得换一条线。MCP 做的事情就是定出一个统一的接口标准让 AI 模型可以通过同一个标准去连接各种外部工具和数据源。在 Claude Figma 这个场景里Claude 就好比一台支持 USB-C 的电脑Figma 设计稿就是外接硬盘。没有 MCP 的时候你想让 Claude 理解设计稿里某个按钮的颜色是什么只能把设计稿截图发给它让它看颜色。但图片里有缩放、有阴影叠加、有图层遮挡AI 看到的颜色往往不是真正的色值。有了 MCP 之后Claude 可以直接调用 Figma 的 API拿到图层的真实节点数据、精确色值、字体字号、间距边距这些数据干净、准确、结构化AI 拿来做分析或生成代码精度完全不在一个量级。从协议架构上看MCP 采用客户端-服务端的模型。Claude 本身是 MCP 客户端HostFigma MCP Server 是一个独立运行的服务进程负责接收 Claude 发来的标准化请求去调用 Figma 的 REST API再把结果转换成统一格式返回给 Claude。整个过程中Claude 不需要知道 Figma API 的细节Figma 也不需要知道 Claude 的调用逻辑MCP 就是中间那个翻译官和信使。1.2 Claude Figma MCP 到底能做什么连线成功之后你可以让 Claude 做的事远超看图说话。我从实际使用经验出发列举几个高频场景。第一类是设计信息提取。比如你给 Claude 一个 Figma 文件链接让它提取某个 Frame 下的所有文本内容、字体样式、颜色变量或者找出所有不符合设计规范的元素。这类任务以前需要设计师手动一个个点开图层检查现在 Claude 可以批量拉取并结构化输出。第二类是设计稿到代码的转换。这是前端同学最关心的场景。让 Claude 读取设计稿的层级结构、布局约束、填充色、圆角、阴影等属性然后生成对应的 HTML/CSS 或 React/Tailwind 代码。关键是 Claude 拿到的是数值和结构不是像素所以生成的代码在尺寸、间距、颜色上能做到和设计稿高度一致。第三类是设计走查与规范校验。你可以让 Claude 检查选中的 Frame 中哪些元素的颜色不属于设计系统的色板哪些字体超出了预设的字体集哪些间距不符合 8pt 网格体系。这类自动化的规范检查在多人协作的大型项目里非常节省时间。第四类是批量修改和重构。比如告诉 Claude把当前页面里所有主按钮的边框圆角从 8 改成 12它可以遍历节点树找到符合条件的元素生成修改建议或直接通过 API 更新文件需要额外权限。1.3 这个方案解决了什么问题在没有 MCP 之前我被设计稿和代码不一致的问题反复折磨。最典型的一个场景设计师说这个按钮的颜色是品牌蓝我在设计稿里用取色器一吸发现偏了两个色号开发照着视觉效果图硬写颜色结果下一个迭代设计稿更新了谁也不知道这个颜色变了。这种信息损耗在传统工作流里几乎无法避免。MCP 的价值在于它把设计稿从一个给人看的静态图片变成了机器可读的结构化数据源。AI 不再靠猜测和视觉识别而是直接读取原始数据。这解决了 AI 落地到设计研发流程中最大的信任问题数据准结果才可靠。此外MCP 的标准化意味着你不需要为每一个 AI 工具单独定制 Figma 插件只要这个工具支持 MCP接上同一个 Server 就能用。这也是我建议团队尽早接入的原因——一次配置多方使用。2. 环境准备与前置条件2.1 准备 Claude 运行环境要把 Claude 作为 MCP 客户端来使用你需要一个支持 MCP 的 Claude 客户端。目前我实测可用的是两条路径一是 Claude Desktop 桌面应用适合配置好后以对话方式使用二是 Claude Code 命令行工具适合开发者在终端里配合编程工作流使用。两条路径的底层 MCP 配置原理是相通的只是配置文件位置和格式略有差异。Claude Code 通常通过 npm 全局安装安装命令很简单但如果你之前没有配置过 Node.js 环境建议先确认 Node 版本在 18 以上。安装完成之后在终端输入 claude 命令就能进入交互界面。如果你遇到claude 无法将项识别为 cmdlet、函数、脚本文件这一类的报错基本可以判定是 npm 全局目录没有加入系统 PATH重新配置一下环境变量路径或者直接用 npx 方式调用问题就解决了。Claude Desktop 则不需要手动管理 npm 环境从官网下载安装包即可。如果你更习惯在图形界面里操作建议优先用 Desktop因为 MCP 工具的调用过程和结果在界面上展示得更直观。2.2 获取 Figma 访问令牌Token要让 MCP Server 能访问你的 Figma 文件你需要提供一个访问令牌。这里的 Token 对应的是 Figma 的 Personal Access Token生成路径是打开 Figma 网页版进入个人设置头像菜单里找到 Security 或安全相关的选项卡点击生成新令牌选好权限范围后复制。生成时 Figma 会要求你选择令牌的作用范围常用的两个是 File content读取文件内容和 File comments读取评论如果只是做设计和代码转换勾选 File content 就够了。有几点需要特别注意。第一Token 是敏感信息它相当于你 Figma 账号的通行证一旦泄露别人就能读取你有权限的所有文件。所以不要把 Token 硬编码在聊天消息里也不要把包含 Token 的配置文件提交到公共仓库。第二Token 有有效期过期后需要重新生成。第三Figma 的 API 是分页返回数据的大文件的读取可能触发超时后面我会讲对应的处理策略。2.3 安装并确认 MCP ServerFigma 官方维护了一个 MCP Servernpm 包名是 figma/mcp-server。这个包负责和 Figma API 通信把文件数据转换成 MCP 协议规定的格式。安装方式有两种一种是通过 npx 临时执行适合快速验证另一种是全局安装适合长期使用。如果你使用 Claude Desktop需要在配置文件里声明这个 Server 的启动命令如果你使用 Claude Code在项目目录下的 .mcp.json 或全局配置里注册即可。各家客户端的配置产品形态还在快速迭代但基本逻辑都一样给 Server 起个名字指定启动命令再提供需要的环境变量。后面我会给出可以直接复制修改的配置内容。2.4 网络与账号权限自查还有两个容易忽略的前提条件。第一Figma 文件必须对你当前登录的账号有访问权限如果你用团队账号登录确认这个文件在团队项目里对你开放了编辑或查看权限。第二不要在一个文件同时有多个协作者强推大改动时做读取测试API 返回的数据会包含版本冲突信息可能让 Claude 产生误解。我建议第一次调试时单独创建一个测试文件画一两个带文字、带颜色、带图层的简单元素把调试环境尽量简化。3. 核心实操完成 Claude 与 Figma 的对接3.1 配置文件写法详解下面我以 Claude Desktop 为例给出一个可以直接操作的流程。首先打开 Claude Desktop 的配置文件在 macOS 上路径是 ~/Library/Application Support/Claude/claude_desktop_config.json在 Windows 上路径是 %APPDATA%\Claude\claude_desktop_config.json。如果你找不到文件可以在设置里选择 Open Config Folder 直接打开配置目录。配置文件是一个 JSON 格式的文本核心结构如下{ mcpServers: { figma: { command: npx, args: [ -y, figma/mcp-server, --stdio ], env: { FIGMA_API_KEY: 你的figma_token填在这里 } } } }这里重点解释几个字段的含义。command 字段是启动命令args 是传给命令的参数我们使用 npx 加 -y 参数来确保每次运行时自动拉取最新版本的 Server 包--stdio 表示用标准输入输出作为通信通道这也是 MCP 最常见的传输方式。env 字段用来注入环境变量Figma MCP Server 通过名为 FIGMA_API_KEY 的环境变量读取你的访问令牌。配置完保存文件之后重启 Claude Desktop。启动时 Claude 会自动拉起 figma MCP Server。你可以在对话界面看到工具列表里多出了和 Figma 相关的工具通常包括获取文件内容、获取图片、获取评论等能力。如果你用的是 Claude Code配置方法类似。在项目根目录创建或修改 .mcp.json写入同样的配置结构进入 claude 交互界面后通过 /mcp 命令可以查看当前已加载的 MCP Server 列表确认 figma 的状态是 connected。3.2 验证连接是否成功配置阶段最容易犯的错误是配了但没有真正连上。连接成功的标志有两点一是 MCP Server 进程能正常启动二是 Claude 能实际调用工具并返回数据。配置文件错了比如 JSON 语法不合法、路径写错、环境变量名拼写错误Server 进程起不来对话里自然看不到工具。启动之后怎么验证最简单的方式是直接向 Claude 提一个需要读取 Figma 数据的请求。比如先准备好一个测试文件的链接对 Claude 说请读取这个 Figma 文件的内容https://www.figma.com/design/xxxxxx/test如果 Claude 返回了文件里所有画板、图层的名称和类型说明链路已经通了。如果它回复我没有访问这个文件的权限或者读取失败那就需要排查了。常见原因无非三类Token 无效、文件权限不足、文件链接格式不对。逐一对照检查即可。Claude Code 用户有个额外的验证技巧在交互界面输入 /mcp 之后能看到每个 Server 的健康状态。figma 状态显示 connected基本就稳了。3.3 从配置文件到可用工具的关键路径如果你第一次配置就不顺利我给你一个逐步排查的思路按顺序检查通常五分钟内能定位问题。第一步检查配置文件本身。JSON 文件最常见的错误是多逗号、缺少引号、注释残留。JSON 不支持注释很多人喜欢把 Example 直接用 # 开头写在里面这会导致整个文件解析失败。判断方法很简单用任意 JSON 格式化工具校验一下格式。第二步确认 npx 能正常拉取到 figma/mcp-server。在终端单独执行 npx -y figma/mcp-server --stdio如果命令卡住不报错说明网络和 npm 源没问题如果提示找不到包检查包名拼写。第三步检查环境变量是否被正确注入。不同的客户端在环境变量处理上有差异比如某些版本对 env 字段的解析有大小写要求FIGMA_API_KEY 是全大写下划线格式不要写成 FigmaApiKey。第四步确认 Figma 文件访问权限。把文件链接用无痕窗口打开看是否能直接访问如果无痕窗口访问不了那 Claude 作为第三方客户端也大概率访问不了。4. 实战场景演示从设计稿数据到前端代码4.1 完整流程一读取设计稿并生成页面代码连接成功后最值得上手试的就是设计稿转代码流程。我先说一下整体步骤再给出一个具体的对话示例。准备阶段你需要在 Figma 里整理好源文件把要转换的页面内容放到一个 Frame 里并给 Frame 起个清晰的名字。这一步很重要因为 Claude 读取文件时是拿节点树的数据Frame 名字相当于给它一个入口。比如我把一个登录页面的所有元素放进了名为Login的 Frame 里。对话开始后你可以这样说读取这个文件里名为 Login 的 Frame分析它的布局结构然后用 React Tailwind CSS 实现这个页面。注意保持原设计稿的配色、间距、字体大小。Claude 会先调用 Figma 工具拿到 Frame 下所有子节点的信息包括矩形、文本、图片、组等元素的类型和属性然后分析它们的层级关系最后生成对应的组件代码。实际体验下来生成结果的准确率取决于源文件的规范程度图层命名越清晰、组件拆分越规整生成的代码质量越高。如果源文件里有一堆Frame 123这样的自动命名Claude 也能处理但生成代码的语义化程度会打折扣。4.2 完整流程二设计走查与规范校验第二个高频场景是设计走查。团队里设计规范通常沉淀在变量和组件库里但人肉检查总有疏漏。MCP 方案适合做一个规范守卫式的自动检查。举例我让 Claude 检查一个电商详情页的 Frame指定如下检查项所有文本的字体是否来自团队的 font-sans 字体集所有主按钮高度是否为 44px所有间距是否为 4 的倍数。读取这个 Frame 里的所有图层属性找出1. 字体不在 Inter 和 PingFang SC 范围内的文本2. 高度不是 44px 的按钮3. 尺寸不是 4 的倍数的最小间距。用表格输出检查结果标注每个元素的名称和具体属性值。Claude 返回的结果会是一张表格里面是每个异常元素的名称、当前值和推荐值。这个能力比截图审查准确得多因为它读的是真实属性数据而不是像素。我用它审查过一个 80 多个组件的后台项目发现了 7 处颜色越界和 3 处字号不一致这些靠人工检查几乎不可能在短时间内找全。4.3 完整流程三组件信息批量提取还有一种经常碰到的场景你接手一个别人的设计稿想知道项目里一共用了多少种颜色、多少种字号、哪些组件被重复使用。手工整理工作量巨大但通过 MCP 调用 Claude几句话就能完成。读取这个文件里所有页面下的所有 Frame统计所有填充颜色出现的次数按次数从高到低排序输出前 10 个统计所有字号的出现频次同样输出前 10 个。这类需求本质上是让 Claude 遍历节点树聚合属性数据。它的输出结构清晰可以直接复制到设计系统文档里作为基础数据。我在做设计系统梳理时用这个功能节省了至少半天的人工统计时间。4.4 实操中的效率技巧与注意点实战过程中有几个注意点值得提一下。第一和 Claude 协作时尽量把任务拆小。一次让它处理读取整个大文件的全部节点大概率超时让它只读取 Login Frame 下的第一层子节点速度快很多。第二在描述需求时明确指定返回格式比如用表格输出用 JSON 输出列出元素名称和属性这样 Claude 的组织结果会更有条理。第三如果涉及图片资源注意 Figma API 对图片渲染有限制大图、复杂阴影的渲染可能需要单独调用图片接口Claude 会通过工具链处理但耗时会更长。第四Claude 读取到的数据是实时的如果有人正在编辑文件结构可能还在变化中协作高峰时段读取结果可能和预期有出入建议在文件稳定的状态下操作。5. 常见问题与排查技巧实录5.1 MCP Server 启动失败与进程挂掉我在配置过程中遇到最多的就是 MCP Server 进程无法启动。现象是 Claude Desktop 里 figma 工具一直显示 loading或者对话中提示 MCP Server error。这类问题 90% 落在三个原因上。第一个是 npx 执行路径问题。某些系统环境下Claude Desktop 通过 shell 调用 npx但 shell 的环境变量不完整导致 npx 路径找不到。解决办法是把 command 从 npx 改成 npx 的绝对路径。在 macOS 上可以通过 which npx 命令查看路径然后填进去。第二个是端口或 stdio 通道冲突。如果你同时在多个客户端里注册了同一个 MCP Server可能导致进程冲突。建议只在正在使用的客户端里保留配置。第三个是 Node 版本太低。figma/mcp-server 对 Node 版本有要求低于某个版本会直接报语法错误。可以通过 node -v 查看当前版本如果低于 18先升级 Node 环境再重启客户端。5.2 Token 相关报错的定位与处理如果你在对话中看到request failed with status code 403或者no token provided之类的错误优先怀疑是 Figma Token 的问题。403 表示鉴权失败原因要么是 Token 过期、要么是 Token 的权限范围不包含该文件的读取权限、要么是 Token 根本就没传进去。排查顺序是先确认配置文件里 FIGMA_API_KEY 环境变量填的是不是最新生成的 Token不要带引号不要带Bearer前缀然后在 Figma 设置里确认 Token 有没有过期如果过期就重新生成并更新配置重启客户端最后用这个 Token 在终端里直接请求一下 Figma API比如 curl 一个文件信息接口如果能返回 JSON说明 Token 本身可用。5.3 大文件读取超时与数据截断Figma 文件越大节点数越多API 响应时间越长MCP Server 默认的超时时间可能不够用。现象是 Claude 说尝试读取文件但操作超时。有两个常规解法。解法一是缩小读取范围。不要把整个文件链接给 Claude而是先通过工具读取到文件里的页面、Frame 列表然后只针对某一个 Frame 请求详细数据。换句话说把一次大请求拆成多次小请求效率反而更高。解法二是在 MCP Server 的启动参数里调整超时配置。具体参数名和客户端相关Claude Code 通常可以设置工具调用的 timeout 上限给它留足余量比如 120 秒。如果你对接的文件特别庞大还可以在 Figma 端把大文件拆成多个页面按需读取这也符合团队协作时按模块分工的习惯。5.4 读取结果与设计稿视觉不一致的根源有时候 Claude 返回的数据在数值上是正确的但生成的效果和设计稿看起来不一样。很多人以为是连接问题其实根源在于 Figma API 返回的数据中包含了一些隐性的设计信息比如混合模式、填充透明度、图层层级遮挡、自动布局的最终计算尺寸等。MCP Server 会把原始属性返回但 Claude 在理解这些属性如何叠加成视觉效果时需要全局上下文。我在实际使用中发现复制设计稿中元素的 clip 属性、导出设置等信息的同时最好在提示词里要求 Claude保留所有图层属性不要做视觉简化。如果发现生成代码里元素顺序乱了大概率是 Claude 没有按节点树的 z 轴顺序排列你可以显式要求它按设计稿里图层从下到上的顺序输出代码。5.5 客户端差异与项目迁移问题如果你在多个客户端间切换注意 MCP 配置是不通用的。Claude Desktop 的配置写在全局配置文件里Claude Code 的配置写在项目目录的 .mcp.json 里两者互不读取。我的建议是日常对话和设计走查用 Desktop代码生成和项目集成用 Code并且把 Token 统一存在系统环境变量里这样两个配置文件只需要写 en 字段的引用方式可以避免多个文件里存了多份 Token减少泄露面。另外如果公司内部有多个设计项目建议为不同项目准备不同的 Figma 团队或文件夹每个 MCP Server 实例绑定最小权限范围避免 AI 在处理时误读不相干文件。这一点在多人合作时尤为重要不仅为了安全也为了减少上下文干扰让 Claude 聚焦在当前任务上。6. 进阶方向与一些个人心得6.1 从单文件读取到多文件聚合MCP 连接稳定之后值得探索的方向是把 Claude Figma 的能力从单文件处理扩展到多文件聚合。Figma API 支持按团队或项目列举文件MCP Server 同样可以暴露这类接口。这意味着你可以让 Claude 遍历整个项目的所有设计文件做一次全量规范检查或统计所有页面里的组件使用情况。这对中大型团队的价值非常大相当于给设计系统装了一个自动巡检机器人。不过多文件聚合要特别注意 Rate Limit。Figma API 对每个账号的请求频率有限制如果你用个人 Token 跑全量扫描很容易触发限流。我的做法是错峰执行在凌晨或中午低峰时段跑批量任务每次任务之间加几秒延时让 Claude 主动休眠一下避免短时间内请求过密。6.2 与代码生成流水线的整合如果你已经在用 Claude 生成前端代码建议把 MCP 能力整合进你的常规工作流而不是当成偶尔用一下的彩蛋。一个切实可行的流程是设计稿更新后先用 Claude 读取变更的 Frame生成一份设计变更说明再基于说明更新代码而不是每次都用整个页面重生成一份完整代码。这样可以大幅降低代码 diff 的噪音也能保持代码架构的一致性。我现在的工作流就时Figma 里改完设计 - Claude 读变更 - 生成差异描述 - 更新对应组件代码。整个流程从原来的一天缩短到两小时左右而且因为数据来源是真实设计属性改动都落在点子上不会像以前那样凭感觉调样式。6.3 关于配置维护与团队复制MCP Server 的配置虽然简单但团队多人落地时还是建议统一维护一份配置说明和自动安装脚本。比如把 npm 包版本锁定避免新成员安装时拉到不同大版本导致行为不一致把 Token 的生成和轮换流程写进团队文档设置提醒机制每 30 天或 60 天轮换一次。这些看起来都是小事在项目紧张时能省掉很多沟通成本。6.4 最后再分享一点经验最后聊一点个人感受。工具本身不难难的是改变使用习惯。刚开始用 Claude Figma MCP 时我还是按照老思路给它发截图让它看着写结果自然不理想。后来逼着自己把设计稿整理规范、把图层命名改清楚、把需求描述写具体工具的效果才真正发挥出来。所以我建议你第一次上手时不要急着拿公司最大最复杂的文件来试先建一个干净的小文件画几个按钮和卡片把流程跑通。流程顺了再逐步应用到真实项目里。这条路我走过一遍稳的。 Claude + Figma MCP 实战：从设计稿数据到前端代码的全流程指南
最近在设计圈和前端圈频繁看到一个组合被讨论Claude Figma MCP。如果你已经尝试过让 AI 帮你写前端代码大概率遇到过AI 写出来的东西跟设计稿完全是两个世界的尴尬。MCP 的出现把让 AI 看图猜设计升级成了让 AI 直接读取设计稿数据这个变化非常实用。这篇教程我会从零开始把 Claude、Figma、MCP 三者的关系讲清楚再一步步带你完成环境配置、连接调试和实战调用期间会穿插我实际踩过的坑和排查经验。无论你是设计师想用 AI 辅助走查还是前端想把设计稿直接转成代码这篇内容都能给你一条直接可走的路径。1. MCP 是什么为什么要把 Claude 和 Figma 连起来1.1 MCP 协议的核心概念与设计思路MCP 全称是 Model Context Protocol直译过来是模型上下文协议。官方定义比较拗口我用一个生活化的类比来讲MCP 就像 AI 世界的 USB-C 接口。以前你给手机充电需要各种品牌专属的充电线换一个设备就得换一条线。MCP 做的事情就是定出一个统一的接口标准让 AI 模型可以通过同一个标准去连接各种外部工具和数据源。在 Claude Figma 这个场景里Claude 就好比一台支持 USB-C 的电脑Figma 设计稿就是外接硬盘。没有 MCP 的时候你想让 Claude 理解设计稿里某个按钮的颜色是什么只能把设计稿截图发给它让它看颜色。但图片里有缩放、有阴影叠加、有图层遮挡AI 看到的颜色往往不是真正的色值。有了 MCP 之后Claude 可以直接调用 Figma 的 API拿到图层的真实节点数据、精确色值、字体字号、间距边距这些数据干净、准确、结构化AI 拿来做分析或生成代码精度完全不在一个量级。从协议架构上看MCP 采用客户端-服务端的模型。Claude 本身是 MCP 客户端HostFigma MCP Server 是一个独立运行的服务进程负责接收 Claude 发来的标准化请求去调用 Figma 的 REST API再把结果转换成统一格式返回给 Claude。整个过程中Claude 不需要知道 Figma API 的细节Figma 也不需要知道 Claude 的调用逻辑MCP 就是中间那个翻译官和信使。1.2 Claude Figma MCP 到底能做什么连线成功之后你可以让 Claude 做的事远超看图说话。我从实际使用经验出发列举几个高频场景。第一类是设计信息提取。比如你给 Claude 一个 Figma 文件链接让它提取某个 Frame 下的所有文本内容、字体样式、颜色变量或者找出所有不符合设计规范的元素。这类任务以前需要设计师手动一个个点开图层检查现在 Claude 可以批量拉取并结构化输出。第二类是设计稿到代码的转换。这是前端同学最关心的场景。让 Claude 读取设计稿的层级结构、布局约束、填充色、圆角、阴影等属性然后生成对应的 HTML/CSS 或 React/Tailwind 代码。关键是 Claude 拿到的是数值和结构不是像素所以生成的代码在尺寸、间距、颜色上能做到和设计稿高度一致。第三类是设计走查与规范校验。你可以让 Claude 检查选中的 Frame 中哪些元素的颜色不属于设计系统的色板哪些字体超出了预设的字体集哪些间距不符合 8pt 网格体系。这类自动化的规范检查在多人协作的大型项目里非常节省时间。第四类是批量修改和重构。比如告诉 Claude把当前页面里所有主按钮的边框圆角从 8 改成 12它可以遍历节点树找到符合条件的元素生成修改建议或直接通过 API 更新文件需要额外权限。1.3 这个方案解决了什么问题在没有 MCP 之前我被设计稿和代码不一致的问题反复折磨。最典型的一个场景设计师说这个按钮的颜色是品牌蓝我在设计稿里用取色器一吸发现偏了两个色号开发照着视觉效果图硬写颜色结果下一个迭代设计稿更新了谁也不知道这个颜色变了。这种信息损耗在传统工作流里几乎无法避免。MCP 的价值在于它把设计稿从一个给人看的静态图片变成了机器可读的结构化数据源。AI 不再靠猜测和视觉识别而是直接读取原始数据。这解决了 AI 落地到设计研发流程中最大的信任问题数据准结果才可靠。此外MCP 的标准化意味着你不需要为每一个 AI 工具单独定制 Figma 插件只要这个工具支持 MCP接上同一个 Server 就能用。这也是我建议团队尽早接入的原因——一次配置多方使用。2. 环境准备与前置条件2.1 准备 Claude 运行环境要把 Claude 作为 MCP 客户端来使用你需要一个支持 MCP 的 Claude 客户端。目前我实测可用的是两条路径一是 Claude Desktop 桌面应用适合配置好后以对话方式使用二是 Claude Code 命令行工具适合开发者在终端里配合编程工作流使用。两条路径的底层 MCP 配置原理是相通的只是配置文件位置和格式略有差异。Claude Code 通常通过 npm 全局安装安装命令很简单但如果你之前没有配置过 Node.js 环境建议先确认 Node 版本在 18 以上。安装完成之后在终端输入 claude 命令就能进入交互界面。如果你遇到claude 无法将项识别为 cmdlet、函数、脚本文件这一类的报错基本可以判定是 npm 全局目录没有加入系统 PATH重新配置一下环境变量路径或者直接用 npx 方式调用问题就解决了。Claude Desktop 则不需要手动管理 npm 环境从官网下载安装包即可。如果你更习惯在图形界面里操作建议优先用 Desktop因为 MCP 工具的调用过程和结果在界面上展示得更直观。2.2 获取 Figma 访问令牌Token要让 MCP Server 能访问你的 Figma 文件你需要提供一个访问令牌。这里的 Token 对应的是 Figma 的 Personal Access Token生成路径是打开 Figma 网页版进入个人设置头像菜单里找到 Security 或安全相关的选项卡点击生成新令牌选好权限范围后复制。生成时 Figma 会要求你选择令牌的作用范围常用的两个是 File content读取文件内容和 File comments读取评论如果只是做设计和代码转换勾选 File content 就够了。有几点需要特别注意。第一Token 是敏感信息它相当于你 Figma 账号的通行证一旦泄露别人就能读取你有权限的所有文件。所以不要把 Token 硬编码在聊天消息里也不要把包含 Token 的配置文件提交到公共仓库。第二Token 有有效期过期后需要重新生成。第三Figma 的 API 是分页返回数据的大文件的读取可能触发超时后面我会讲对应的处理策略。2.3 安装并确认 MCP ServerFigma 官方维护了一个 MCP Servernpm 包名是 figma/mcp-server。这个包负责和 Figma API 通信把文件数据转换成 MCP 协议规定的格式。安装方式有两种一种是通过 npx 临时执行适合快速验证另一种是全局安装适合长期使用。如果你使用 Claude Desktop需要在配置文件里声明这个 Server 的启动命令如果你使用 Claude Code在项目目录下的 .mcp.json 或全局配置里注册即可。各家客户端的配置产品形态还在快速迭代但基本逻辑都一样给 Server 起个名字指定启动命令再提供需要的环境变量。后面我会给出可以直接复制修改的配置内容。2.4 网络与账号权限自查还有两个容易忽略的前提条件。第一Figma 文件必须对你当前登录的账号有访问权限如果你用团队账号登录确认这个文件在团队项目里对你开放了编辑或查看权限。第二不要在一个文件同时有多个协作者强推大改动时做读取测试API 返回的数据会包含版本冲突信息可能让 Claude 产生误解。我建议第一次调试时单独创建一个测试文件画一两个带文字、带颜色、带图层的简单元素把调试环境尽量简化。3. 核心实操完成 Claude 与 Figma 的对接3.1 配置文件写法详解下面我以 Claude Desktop 为例给出一个可以直接操作的流程。首先打开 Claude Desktop 的配置文件在 macOS 上路径是 ~/Library/Application Support/Claude/claude_desktop_config.json在 Windows 上路径是 %APPDATA%\Claude\claude_desktop_config.json。如果你找不到文件可以在设置里选择 Open Config Folder 直接打开配置目录。配置文件是一个 JSON 格式的文本核心结构如下{ mcpServers: { figma: { command: npx, args: [ -y, figma/mcp-server, --stdio ], env: { FIGMA_API_KEY: 你的figma_token填在这里 } } } }这里重点解释几个字段的含义。command 字段是启动命令args 是传给命令的参数我们使用 npx 加 -y 参数来确保每次运行时自动拉取最新版本的 Server 包--stdio 表示用标准输入输出作为通信通道这也是 MCP 最常见的传输方式。env 字段用来注入环境变量Figma MCP Server 通过名为 FIGMA_API_KEY 的环境变量读取你的访问令牌。配置完保存文件之后重启 Claude Desktop。启动时 Claude 会自动拉起 figma MCP Server。你可以在对话界面看到工具列表里多出了和 Figma 相关的工具通常包括获取文件内容、获取图片、获取评论等能力。如果你用的是 Claude Code配置方法类似。在项目根目录创建或修改 .mcp.json写入同样的配置结构进入 claude 交互界面后通过 /mcp 命令可以查看当前已加载的 MCP Server 列表确认 figma 的状态是 connected。3.2 验证连接是否成功配置阶段最容易犯的错误是配了但没有真正连上。连接成功的标志有两点一是 MCP Server 进程能正常启动二是 Claude 能实际调用工具并返回数据。配置文件错了比如 JSON 语法不合法、路径写错、环境变量名拼写错误Server 进程起不来对话里自然看不到工具。启动之后怎么验证最简单的方式是直接向 Claude 提一个需要读取 Figma 数据的请求。比如先准备好一个测试文件的链接对 Claude 说请读取这个 Figma 文件的内容https://www.figma.com/design/xxxxxx/test如果 Claude 返回了文件里所有画板、图层的名称和类型说明链路已经通了。如果它回复我没有访问这个文件的权限或者读取失败那就需要排查了。常见原因无非三类Token 无效、文件权限不足、文件链接格式不对。逐一对照检查即可。Claude Code 用户有个额外的验证技巧在交互界面输入 /mcp 之后能看到每个 Server 的健康状态。figma 状态显示 connected基本就稳了。3.3 从配置文件到可用工具的关键路径如果你第一次配置就不顺利我给你一个逐步排查的思路按顺序检查通常五分钟内能定位问题。第一步检查配置文件本身。JSON 文件最常见的错误是多逗号、缺少引号、注释残留。JSON 不支持注释很多人喜欢把 Example 直接用 # 开头写在里面这会导致整个文件解析失败。判断方法很简单用任意 JSON 格式化工具校验一下格式。第二步确认 npx 能正常拉取到 figma/mcp-server。在终端单独执行 npx -y figma/mcp-server --stdio如果命令卡住不报错说明网络和 npm 源没问题如果提示找不到包检查包名拼写。第三步检查环境变量是否被正确注入。不同的客户端在环境变量处理上有差异比如某些版本对 env 字段的解析有大小写要求FIGMA_API_KEY 是全大写下划线格式不要写成 FigmaApiKey。第四步确认 Figma 文件访问权限。把文件链接用无痕窗口打开看是否能直接访问如果无痕窗口访问不了那 Claude 作为第三方客户端也大概率访问不了。4. 实战场景演示从设计稿数据到前端代码4.1 完整流程一读取设计稿并生成页面代码连接成功后最值得上手试的就是设计稿转代码流程。我先说一下整体步骤再给出一个具体的对话示例。准备阶段你需要在 Figma 里整理好源文件把要转换的页面内容放到一个 Frame 里并给 Frame 起个清晰的名字。这一步很重要因为 Claude 读取文件时是拿节点树的数据Frame 名字相当于给它一个入口。比如我把一个登录页面的所有元素放进了名为Login的 Frame 里。对话开始后你可以这样说读取这个文件里名为 Login 的 Frame分析它的布局结构然后用 React Tailwind CSS 实现这个页面。注意保持原设计稿的配色、间距、字体大小。Claude 会先调用 Figma 工具拿到 Frame 下所有子节点的信息包括矩形、文本、图片、组等元素的类型和属性然后分析它们的层级关系最后生成对应的组件代码。实际体验下来生成结果的准确率取决于源文件的规范程度图层命名越清晰、组件拆分越规整生成的代码质量越高。如果源文件里有一堆Frame 123这样的自动命名Claude 也能处理但生成代码的语义化程度会打折扣。4.2 完整流程二设计走查与规范校验第二个高频场景是设计走查。团队里设计规范通常沉淀在变量和组件库里但人肉检查总有疏漏。MCP 方案适合做一个规范守卫式的自动检查。举例我让 Claude 检查一个电商详情页的 Frame指定如下检查项所有文本的字体是否来自团队的 font-sans 字体集所有主按钮高度是否为 44px所有间距是否为 4 的倍数。读取这个 Frame 里的所有图层属性找出1. 字体不在 Inter 和 PingFang SC 范围内的文本2. 高度不是 44px 的按钮3. 尺寸不是 4 的倍数的最小间距。用表格输出检查结果标注每个元素的名称和具体属性值。Claude 返回的结果会是一张表格里面是每个异常元素的名称、当前值和推荐值。这个能力比截图审查准确得多因为它读的是真实属性数据而不是像素。我用它审查过一个 80 多个组件的后台项目发现了 7 处颜色越界和 3 处字号不一致这些靠人工检查几乎不可能在短时间内找全。4.3 完整流程三组件信息批量提取还有一种经常碰到的场景你接手一个别人的设计稿想知道项目里一共用了多少种颜色、多少种字号、哪些组件被重复使用。手工整理工作量巨大但通过 MCP 调用 Claude几句话就能完成。读取这个文件里所有页面下的所有 Frame统计所有填充颜色出现的次数按次数从高到低排序输出前 10 个统计所有字号的出现频次同样输出前 10 个。这类需求本质上是让 Claude 遍历节点树聚合属性数据。它的输出结构清晰可以直接复制到设计系统文档里作为基础数据。我在做设计系统梳理时用这个功能节省了至少半天的人工统计时间。4.4 实操中的效率技巧与注意点实战过程中有几个注意点值得提一下。第一和 Claude 协作时尽量把任务拆小。一次让它处理读取整个大文件的全部节点大概率超时让它只读取 Login Frame 下的第一层子节点速度快很多。第二在描述需求时明确指定返回格式比如用表格输出用 JSON 输出列出元素名称和属性这样 Claude 的组织结果会更有条理。第三如果涉及图片资源注意 Figma API 对图片渲染有限制大图、复杂阴影的渲染可能需要单独调用图片接口Claude 会通过工具链处理但耗时会更长。第四Claude 读取到的数据是实时的如果有人正在编辑文件结构可能还在变化中协作高峰时段读取结果可能和预期有出入建议在文件稳定的状态下操作。5. 常见问题与排查技巧实录5.1 MCP Server 启动失败与进程挂掉我在配置过程中遇到最多的就是 MCP Server 进程无法启动。现象是 Claude Desktop 里 figma 工具一直显示 loading或者对话中提示 MCP Server error。这类问题 90% 落在三个原因上。第一个是 npx 执行路径问题。某些系统环境下Claude Desktop 通过 shell 调用 npx但 shell 的环境变量不完整导致 npx 路径找不到。解决办法是把 command 从 npx 改成 npx 的绝对路径。在 macOS 上可以通过 which npx 命令查看路径然后填进去。第二个是端口或 stdio 通道冲突。如果你同时在多个客户端里注册了同一个 MCP Server可能导致进程冲突。建议只在正在使用的客户端里保留配置。第三个是 Node 版本太低。figma/mcp-server 对 Node 版本有要求低于某个版本会直接报语法错误。可以通过 node -v 查看当前版本如果低于 18先升级 Node 环境再重启客户端。5.2 Token 相关报错的定位与处理如果你在对话中看到request failed with status code 403或者no token provided之类的错误优先怀疑是 Figma Token 的问题。403 表示鉴权失败原因要么是 Token 过期、要么是 Token 的权限范围不包含该文件的读取权限、要么是 Token 根本就没传进去。排查顺序是先确认配置文件里 FIGMA_API_KEY 环境变量填的是不是最新生成的 Token不要带引号不要带Bearer前缀然后在 Figma 设置里确认 Token 有没有过期如果过期就重新生成并更新配置重启客户端最后用这个 Token 在终端里直接请求一下 Figma API比如 curl 一个文件信息接口如果能返回 JSON说明 Token 本身可用。5.3 大文件读取超时与数据截断Figma 文件越大节点数越多API 响应时间越长MCP Server 默认的超时时间可能不够用。现象是 Claude 说尝试读取文件但操作超时。有两个常规解法。解法一是缩小读取范围。不要把整个文件链接给 Claude而是先通过工具读取到文件里的页面、Frame 列表然后只针对某一个 Frame 请求详细数据。换句话说把一次大请求拆成多次小请求效率反而更高。解法二是在 MCP Server 的启动参数里调整超时配置。具体参数名和客户端相关Claude Code 通常可以设置工具调用的 timeout 上限给它留足余量比如 120 秒。如果你对接的文件特别庞大还可以在 Figma 端把大文件拆成多个页面按需读取这也符合团队协作时按模块分工的习惯。5.4 读取结果与设计稿视觉不一致的根源有时候 Claude 返回的数据在数值上是正确的但生成的效果和设计稿看起来不一样。很多人以为是连接问题其实根源在于 Figma API 返回的数据中包含了一些隐性的设计信息比如混合模式、填充透明度、图层层级遮挡、自动布局的最终计算尺寸等。MCP Server 会把原始属性返回但 Claude 在理解这些属性如何叠加成视觉效果时需要全局上下文。我在实际使用中发现复制设计稿中元素的 clip 属性、导出设置等信息的同时最好在提示词里要求 Claude保留所有图层属性不要做视觉简化。如果发现生成代码里元素顺序乱了大概率是 Claude 没有按节点树的 z 轴顺序排列你可以显式要求它按设计稿里图层从下到上的顺序输出代码。5.5 客户端差异与项目迁移问题如果你在多个客户端间切换注意 MCP 配置是不通用的。Claude Desktop 的配置写在全局配置文件里Claude Code 的配置写在项目目录的 .mcp.json 里两者互不读取。我的建议是日常对话和设计走查用 Desktop代码生成和项目集成用 Code并且把 Token 统一存在系统环境变量里这样两个配置文件只需要写 en 字段的引用方式可以避免多个文件里存了多份 Token减少泄露面。另外如果公司内部有多个设计项目建议为不同项目准备不同的 Figma 团队或文件夹每个 MCP Server 实例绑定最小权限范围避免 AI 在处理时误读不相干文件。这一点在多人合作时尤为重要不仅为了安全也为了减少上下文干扰让 Claude 聚焦在当前任务上。6. 进阶方向与一些个人心得6.1 从单文件读取到多文件聚合MCP 连接稳定之后值得探索的方向是把 Claude Figma 的能力从单文件处理扩展到多文件聚合。Figma API 支持按团队或项目列举文件MCP Server 同样可以暴露这类接口。这意味着你可以让 Claude 遍历整个项目的所有设计文件做一次全量规范检查或统计所有页面里的组件使用情况。这对中大型团队的价值非常大相当于给设计系统装了一个自动巡检机器人。不过多文件聚合要特别注意 Rate Limit。Figma API 对每个账号的请求频率有限制如果你用个人 Token 跑全量扫描很容易触发限流。我的做法是错峰执行在凌晨或中午低峰时段跑批量任务每次任务之间加几秒延时让 Claude 主动休眠一下避免短时间内请求过密。6.2 与代码生成流水线的整合如果你已经在用 Claude 生成前端代码建议把 MCP 能力整合进你的常规工作流而不是当成偶尔用一下的彩蛋。一个切实可行的流程是设计稿更新后先用 Claude 读取变更的 Frame生成一份设计变更说明再基于说明更新代码而不是每次都用整个页面重生成一份完整代码。这样可以大幅降低代码 diff 的噪音也能保持代码架构的一致性。我现在的工作流就时Figma 里改完设计 - Claude 读变更 - 生成差异描述 - 更新对应组件代码。整个流程从原来的一天缩短到两小时左右而且因为数据来源是真实设计属性改动都落在点子上不会像以前那样凭感觉调样式。6.3 关于配置维护与团队复制MCP Server 的配置虽然简单但团队多人落地时还是建议统一维护一份配置说明和自动安装脚本。比如把 npm 包版本锁定避免新成员安装时拉到不同大版本导致行为不一致把 Token 的生成和轮换流程写进团队文档设置提醒机制每 30 天或 60 天轮换一次。这些看起来都是小事在项目紧张时能省掉很多沟通成本。6.4 最后再分享一点经验最后聊一点个人感受。工具本身不难难的是改变使用习惯。刚开始用 Claude Figma MCP 时我还是按照老思路给它发截图让它看着写结果自然不理想。后来逼着自己把设计稿整理规范、把图层命名改清楚、把需求描述写具体工具的效果才真正发挥出来。所以我建议你第一次上手时不要急着拿公司最大最复杂的文件来试先建一个干净的小文件画几个按钮和卡片把流程跑通。流程顺了再逐步应用到真实项目里。这条路我走过一遍稳的。