1. 为什么值得折腾先看清问题再谈方案1.1 设计稿交接本质上是信息损耗问题开发做得久了你会意识到日常最高频的沟通成本根本不在写代码而在反复确认设计稿上的细节。按钮的 hover 状态是什么颜色、列表项间距是 12 还是 16、某个插画的圆角到底是多少——每个问题单独看都不算大但叠加在一起一天下来大量时间就耗在这些琐碎确认上。更麻烦的是这种确认往往不是一次性的设计稿改版一次你就要重新核对一遍。如果只是人肉确认也就罢了当你把 Codex 这类 AI 编程工具引入工作流之后新的问题又来了你需要把设计稿信息转述给 Agent。而任何转述都是信息损耗你漏掉一个 paddingAI 生成的样式就跟着错标注图上没写字号AI 就只能靠猜。设计稿明明就在那里Figma 文件里的属性也都是结构化数据为什么偏偏要靠嘴去传话这就是我折腾 Local Figma Agent MCP 的初衷让 Agent 直接“打开”设计稿去读而不是等我一点点喂它。它表面上是一个插件本质上是在 Codex 和 Figma 之间搭了一条数据通道让设计稿里的图层结构、样式参数、文本内容都能变成 AI 可以直接调用的结构化信息。1.2 付费套餐不是不能买而是没必要市面上确实有不少把 Figma 集成进 AI 工作流的现成方案最省事的通常是订阅某个带原生 Figma 连接的 AI 套餐。但那个价格放在个人开发者或者小项目里确实肉疼。更关键的是大部分场景下你只需要读取几个节点、导出几处样式为这点需求长期付费我觉得非常不划算。社区里其实早就有一批 Figma 相关的 MCP 服务器MCPModel Context Protocol本身就是一种让 AI 客户端调用外部工具的标准协议。只是多数做得比较完整的方案要么把自己包装成云端托管服务要么绑定某个商业产品的账号体系变相把免费用户挡在门外。而 Local Figma Agent MCP 的思路完全不同MCP 服务器本身跑在你自己的机器上使用你自己的 Figma 凭据去访问设计稿。没有中间商没有订阅费只要你的电脑能跑 Node.js这套东西就能跑起来。付费方案当然有它的省心之处但如果你只是想给自己的开发流程加一双眼睛不额外花钱的方案已经足够好用。1.3 它解决的三个具体痛点用一个本地进程打通 Codex 和 Figma解决的不只是省钱问题至少有三点体验上的提升是我实际用下来才感受到的。第一数据不经过第三方托管。设计稿属性、图层结构这些信息经过的是你本机的服务和 Figma 官方接口不会绕到某个陌生平台再转一手安全性上踏实很多。第二响应速度和自由度。本地 MCP 服务可以自己改想加工具函数就加想调整缓存策略就调整不受云端产品功能边界的约束。第三能与本地工作流深度融合。它可以把读取到的设计节点缓存到项目目录里Agent 后续写代码时直接参考本地 JSON 文件而不是每次都要重新请求接口。2. 工作原理Local Figma Agent MCP 怎么打通两端2.1 先理解 MCP 的三角关系要搞懂 Local Figma Agent MCP先得理解 MCP 的协作模型。它本质上涉及三方MCP 客户端比如 Codex、MCP 服务器、以及被操作的目标应用Figma。MCP 客户端不会直接去操作目标应用而是向 MCP 服务器发起工具调用。服务器把目标应用的能力封装成一个个“工具”比如读取文件信息、按 ID 查询节点、导出节点样式、批量修改节点属性等等。AI 在对话中根据你的指令判断该调用哪个工具由服务器去执行再把结果以结构化形式回传给 AIAI 基于结果继续推理。这种解耦的好处非常明显。客户端只需要一套标准的调用协议具体到某个应用的能力细节全部藏在服务器里。这跟 USB-C 接口的思路有点像协议统一了不同设备才能互相插拔。正因为它是一套开放标准你不需要等某个 AI 平台专门为 Figma 做集成自己就能接上。2.2 读取能力把设计稿变成 Agent 能看懂的 JSONLocal Figma Agent 的核心读取能力是把 Figma 文档结构映射成结构化数据。具体来说它通常会把设计稿拆成几个层面来暴露给 Agent文件级信息文件名称、版本、画布列表。节点级信息页面、Frame、Group、Text、Vector 等节点的完整树结构。样式级信息填充色、描边、圆角、间距、字体、字号、字重等属性。一个 Frame 在 Figma 编辑器里展示的是视觉层但在 MCP 服务器看来它就是一个带有完整属性的 JSON 对象。Agent 通过工具拿到这个对象后就能自己读懂布局规则和视觉规范。这带来的好处是质的改变——AI 不用再靠你口述“这个按钮是蓝底白字圆角 8px”它自己就能从设计稿里读到准确数值而且比你手动读还可靠。2.3 修改能力不只是“读”还能“写”标题里说“读懂并修改”修改这块很多现成方案是做不到的原因在于 Figma 官方 REST API 对写操作的支持非常有限只能改少量元数据。Local Figma Agent 能改靠的是本地通道。具体的实现方式通常是这样的MCP 服务器启动后会去侦听本机 Figma 桌面客户端暴露的本地端口借用桌面端已登录的会话做增强操作。之所以能写入是因为桌面客户端本身具备完整的编辑能力本地脚本只是把修改指令通过内部端口提交给它执行。常见的修改能力包括改图层名、调整文本节点的文字内容、修改填充色、复制节点、甚至重新排列组内顺序。这些操作手动做很繁琐但用 Agent 批量做就非常有价值了。2.4 本地化为什么不是自找麻烦有人会问放在本地跑难道不是自找麻烦吗云端方案明明开箱即用。我觉得这个判断要分场景。偶尔看一份设计稿云服务确实省心但如果你整天跟 Figma 打交道希望 AI 稳定地、批量地处理设计稿信息本地方案反而更可靠。不依赖别人的服务稳定性不需要排队也不受远端配额限制。本地还能做缓存跑一次完整的文件树解析之后所有对话都可以复用不用反复请求。3. 搭建步骤从零配置 Local Figma Agent 与 Codex3.1 环境准备清单动手之前先清点环境。我实际跑通的组合是这样的Node.js 版本 18 以上、本地安装 Figma 桌面客户端、已有 Codex 环境、一个对目标设计稿具备编辑权限的 Figma 账号。Node.js 是运行时版本建议 18 以上具体看 MCP 服务器要求。Figma 桌面客户端的用途前面说过了修改能力需要它配合如果只做纯读取只用个人访问令牌就够了。Codex 这边要确认支持 MCP 配置市面上主流 AI 编程工具基本都有这个能力只是配置入口略有差别。3.2 获取 Figma 访问凭据有两种拿凭据的方式取决于你需要什么能力。纯读取的话最省事的是创建 Figma 个人访问令牌。在 Figma 账号设置里进入个人访问令牌页面新建一个带 Files: Read 权限的 token 记录下来。注意这个 token 要像密码一样保存它一旦泄露别人就能看到你有权限访问的所有设计稿内容。如果需要修改光靠官方 API 改不了多少东西。这时候 Local Figma Agent 走的是另一条路侦听本机 Figma 桌面客户端暴露的本地端口借用它的本地会话去执行写操作。这种方式不需要额外 token因为登录状态就是你桌面客户端的登录状态你本人在 Figma 里能改什么Agent 就能通过本地通道改什么。3.3 启动本地 MCP 服务拿到凭据后启动服务就很简单了。社区里这类项目一般是 Node 项目克隆到本地后安装依赖配置好环境变量然后执行启动命令# 安装依赖 npm install # 配置环境变量具体变量名以你使用的项目为准 export FIGMA_TOKENfigd_你的Token export FIGMA_LOCAL_PORT18382 # 启动 MCP 服务器 npm start跑起来之后终端会打印类似 “MCP server running on stdio” 或 “listening on 127.0.0.1:xxxx” 的日志。看到这个输出说明服务器进程已经就绪正在等待 MCP 客户端接入。这个阶段如果报依赖缺失优先检查 Node 版本升级到 18 以上基本能解决。3.4 把 MCP 注册给 Codex服务器跑起来了还要让 Codex 知道去哪里找它。Codex 这类工具一般通过配置文件或内置命令添加 MCP 服务器。配置文件里 JSON 结构大致是这样{ mcpServers: { figma-agent: { command: npx, args: [figma-agent-mcp], env: { FIGMA_TOKEN: figd_你的Token } } } }有的客户端支持在终端直接执行添加命令原理同样是把上面这段注册信息写进配置。需要注意command 路径要用绝对路径或保证 npx 在 PATH 里否则客户端启动 MCP 服务器时会找不到命令。配置完重启 Codex它才会重新加载服务器列表。3.5 连通性验证配置完成后先别急着干正事做一次最小验证。在 Codex 对话里发一句“调用 figma 工具读取测试文件第一帧的基本信息。”如果 Agent 能返回画布名称、尺寸、子节点数量这些结构化信息说明链路已经通了。这一步能排查掉一半的配置问题非常值得花两分钟做。4. 实战场景让 Agent 读懂并修改设计稿4.1 场景一一句话拉出整套设计规范我最常用的场景是让 Agent 扫描设计稿里的文字与颜色系统。对着一整个 Frame 发指令“读取这个 Frame 下所有 Text 节点列出每个节点的字号、字重、颜色并按字号分组统计。”Local Figma Agent 会把 Frame 下所有文本节点解析出来整理成 Markdown 表格返回。你会得到一份直接从设计稿生成的样式清单不需要再人肉点选图层一个个查看右侧属性面板。这个操作的效率提升很直观以前人工做要花上小半天现在 AI 批量读一遍结果几乎不出错。而且因为是直接读的 JSON后续把它转成设计变量或注释都是一条命令的事。4.2 场景二让 Agent 直接修改设计稿里的文案修改功能是 Local Figma Agent 相对纯读取方案的优势所在也是最容易被忽视的价值。举个例子设计稿里有一批按钮文案是“了解更多”功能上线前产品要求统一改成“立即查看”。手动改十几个画板里的同名文案容易漏也容易手滑改错地方。用本地 Agent我直接对 Codex 说“把所有取名为 btn_text 的 Text 节点内容统一替换为‘立即查看’不要动其他节点。”Agent 会调用本地写入通道按节点名筛选批量替换文本内容完成后汇报修改了哪些位置。这种按命名批量修改的场景脚本化比人肉可靠得多前提是设计稿团队愿意维护好图层命名规范。4.3 场景三设计稿转代码前的规格提取前端拿到设计稿第一件事是量尺寸、取色、对间距。没有 Agent 的时候全靠浏览器里开着 Figma 一点一点查。现在我会让 Agent 做预结构化“读取指定 Frame 节点输出每个子节点的 name、x、y、width、height、填充颜色、圆角按层级缩进排列。”返回的 JSON 结构清晰Agent 可以直接基于它生成对应的语义化 CSS。转出来的样式和设计稿数据是同一份来源对不上的概率大幅降低。实测下来以前一版页面要花一上午做还原现在把设计规范提取这部分交出去人可以专注在业务逻辑上。4.4 实际操作里的几个关键参数熟练之后你会发现把指令发准确比学会调用工具更重要。这里有两个最常用的参数需要理解depth读取的子层深度上限。默认读全部节点多的时候响应会非常慢建议按需限制层级。include_styles是否附带样式解析结果。需要取色、字体时开启否则关掉提速。Figma 文件动辄几千个节点一次性全量拉取不仅慢还容易把 AI 的上下文撑爆。学会限制读取范围你的请求会更稳定Agent 的回答也会更聚焦。另外指定节点时优先用节点 ID 而不是节点名称因为名称可能重复ID 是唯一的。5. 常见问题与排查记录5.1 读取失败鉴权报错最常遇到的是 403 或 token 失效。排查顺序我总结了四条先确认 token 有 Files: Read 权限再看 token 有没有过期接着确认账号对目标文件有编辑权限最后检查是不是文件本身的访问权限设置限制了你。个人 token 无法覆盖团队受保护文件的情况换本地会话通道是最快的解法。5.2 节点读不出来这类问题隐蔽性强我踩得最多的是坐标空间混淆。如果你拿到的 x/y 和设计稿里显示的不一致多半是缩放比例导致注意 API 返回的是绝对画布坐标而不是屏幕像素。另一个高频坑是节点 ID 里的冒号丢失。Figma 的节点 ID 长这样123:456传参时如果做过字符串转义冒号经常会被吃掉导致找不到节点。解析时保留原始字符串不做多余格式化能避免大多数问题。5.3 修改不生效本地修改通道对桌面客户端版本敏感。Figma 桌面版升级后本地端口行为可能变化表现就是 Agent 反馈“已修改”但设计稿纹丝不动。这时候重启 Figma 桌面端让 MCP 服务器重新连接本地端口基本能解决。另一个建议修改文本内容前先让 Agent 把原值快照存一份。否则改完发现文案写错了想恢复没有原值就只能手工补非常被动。5.4 性能与限流问题文件太大导致读取超时优先增加工具的超时时间或者用 depth 参数限制读取深度。频繁请求触发限流也很常见Figma 对个人 token 的请求频率有严格限制解决方案是把读取结果缓存到本地 JSON 文件后续对话直接读缓存不再请求接口。本地端口被占用时检查是否有其他进程占用了 MCP 配置的端口换一个即可。我把几类高频问题整理成了一张速查表方便对照现象可能原因快速解法403 / token 失效token 权限不足或过期重新生成 token确认 Files: Read节点返回空文件受保护或 ID 格式错误检查访问权限保留节点 ID 原始格式坐标对不上混淆画布坐标和像素坐标以 API 返回的绝对画布坐标为准修改无效果本地端口连接断开重启 Figma 桌面端重新连接读取超时全量拉取节点过多设置 depth 限制或缓存到本地请求被限流短时间内请求过多写本地缓存避免重复请求6. 个人体会与进阶方向说几句实话。这个方案的价值不在于省了多少订阅费而在于把设计稿变成了可编程的资源。我实际用下来最舒服的反而是开会前用 Agent 扫一遍最新设计稿自动生成变更摘要哪些组件更新了、哪些颜色变了、哪些文案调整了。不用自己打开文件核对AI 直接汇报体验完全不一样。当然它也有边界。遇到非常复杂的交互稿涉及原型连线、交互流、状态切换这些需要看动效演示的内容文字和 JSON 结构表达不了真到了那一步还是得打开 Figma 自己看。工具解决的是结构化和批量处理问题替代不了人对视觉的判断这一点要放平预期。如果后续想继续扩展我建议这样玩把本地 MCP 服务接进 CI每次设计稿更新后自动跑一遍规格提取产出给前端使用的 JSON自己给 MCP 服务器写新工具函数让 Agent 能对比两个版本的差异并输出变更日志再进一步跟本地代码库联动Agent 改完设计稿之后直接同步修改项目里的样式变量文件。最后分享一个我踩过几次坑之后形成的习惯每次做修改类操作之前先让 Agent 把原始节点快照存一份。别图省事这个习惯在后期做恢复、做对比时能替你省出大把时间也让整个流程变得可回滚、可审计。工具是让人更放心的而不是制造新的不可控这是我折腾这一圈最大的感受。