1. 为什么值得折腾：先看清问题再谈方案
1.1 设计稿交接，本质上是信息损耗问题
开发做得久了，你会意识到日常最高频的沟通成本根本不在写代码，而在反复确认设计稿上的细节。按钮的 hover 状态是什么颜色、列表项间距是 12 还是 16、某个插画的圆角到底是多少——每个问题单独看都不算大，但叠加在一起，一天下来大量时间就耗在这些琐碎确认上。更麻烦的是，这种确认往往不是一次性的，设计稿改版一次，你就要重新核对一遍。
如果只是人肉确认也就罢了，当你把 Codex 这类 AI 编程工具引入工作流之后，新的问题又来了：你需要把设计稿信息转述给 Agent。而任何转述都是信息损耗，你漏掉一个 padding，AI 生成的样式就跟着错；标注图上没写字号，AI 就只能靠猜。设计稿明明就在那里，Figma 文件里的属性也都是结构化数据，为什么偏偏要靠嘴去传话？
这就是我折腾 Local Figma Agent MCP 的初衷：让 Agent 直接“打开”设计稿去读，而不是等我一点点喂它。它表面上是一个插件，本质上是在 Codex 和 Figma 之间搭了一条数据通道，让设计稿里的图层结构、样式参数、文本内容都能变成 AI 可以直接调用的结构化信息。
1.2 付费套餐不是不能买，而是没必要
市面上确实有不少把 Figma 集成进 AI 工作流的现成方案，最省事的通常是订阅某个带原生 Figma 连接的 AI 套餐。但那个价格放在个人开发者或者小项目里，确实肉疼。更关键的是，大部分场景下你只需要读取几个节点、导出几处样式，为这点需求长期付费，我觉得非常不划算。
社区里其实早就有一批 Figma 相关的 MCP 服务器，MCP（Model 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 在对话中根据你的指令判断该调用哪个工具，由服务器去执行，再把结果以结构化形式回传给 AI，AI 基于结果继续推理。
这种解耦的好处非常明显。客户端只需要一套标准的调用协议，具体到某个应用的能力细节全部藏在服务器里。这跟 USB-C 接口的思路有点像，协议统一了，不同设备才能互相插拔。正因为它是一套开放标准，你不需要等某个 AI 平台专门为 Figma 做集成，自己就能接上。
2.2 读取能力：把设计稿变成 Agent 能看懂的 JSON
Local 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 与 Codex
3.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_TOKEN="figd_你的Token" export FIGMA_LOCAL_PORT="18382" # 启动 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 把原始节点快照存一份。别图省事，这个习惯在后期做恢复、做对比时能替你省出大把时间，也让整个流程变得可回滚、可审计。工具是让人更放心的，而不是制造新的不可控，这是我折腾这一圈最大的感受。
