用MCP协议打通AI Agent与Figma：设计稿自动化修改实战

我去年年底就在琢磨一件事现在 AI Agent 已经能写代码、改文档、操作浏览器了那设计稿呢能不能让 Agent 直接去改 Figma于是在朋友的怂恿下我们花了三周时间做了一个开源项目把 Agent 和 Figma 用 MCP 协议打通核心就一句话——你给 Agent 一句话它自己打开设计稿、读取图层、改文本、调布局、导图一气呵成。这篇文章就把它从原理到落地完整拆给你。先说清楚这东西适合谁手上经常要维护 Figma 设计稿、又不想反复切工具的设计师和前端还有在折腾 Agent 技能栈、想给 Agent 接图型工具的开发者。如果你只是偶尔打开一下 Figma这篇也能让你少踩不少坑。1. 项目概述与设计思路1.1 传统设计稿修改流程为什么那么慢在聊开源项目之前得先复盘一个几乎每个团队都踩过的问题——设计稿改动链路太长了。比如产品和运营提了一个需求首页 banner 文案要换、字号要放大、卡片间距要调。放到传统流程里顺序一般是这样的产品从需求池里贴一段说明设计师打开 Figma 找到对应页面先把图层树翻一遍再逐层找到文本框、间距属性和样式变量然后手动改。改完还要截图发群里开发确认效果开发再照着标注去调前端代码。这条链路的问题不在于某一个人慢而是每一步都在消耗上下文。设计师需要先理解需求再在几十个图层里做“信息检索”最后才能动手开发根据截图努力还原真实设计意图。这样一个改动来回几轮快则半小时慢则一整天。要是团队里有人临时改了设计变量整个链路就再重新来一遍。其实这个痛点的本质是设计数据是结构化的但操作环节被人为切成了一段段手工流程。而 Agent 这类工具最擅长的正是结构化数据解析和任务分解。那我们自然要问一句能不能把“找图层、改属性”这件事直接交给 Agent1.2 开源项目的核心定位让 Agent 成为设计稿协作者我们做的这个开源项目全名叫figma-agent-bridge简称 FAB。它做的事情用一句话概括通过 MCP 协议把 Figma 设计稿暴露给 Agent 作为一组标准工具让 Agent 能读取、理解、修改并导出设计稿。那它和蔡郁那些卖课的“AI 设计工具”有什么本质不同三点它跑在你自己的环境里Figma 文件的数据不会上传到第三方 AI 平台整个链路由你掌控。它基于 MCP 标准协议不绑定某一个 Agent。今天你可以接到 Claude Desktop、Cursor 上明天也能换到自研 Agent适配成本几乎为零。它不仅仅能“生成”设计稿而是直接操作现有设计稿。这对真实团队的价值比“从零生成”更大因为真实项目里设计稿是已经沉淀好的资产。整个项目的结构其实很简单一个 MCP Server负责和 Agent 对话一个 Figma 插件负责在 Figma 内部真正执行修改。后者是可选的因为我后面会讲有些只读操作靠 REST API 就够了但改图层这类“写”操作目前插件桥接是最稳的方式。提示我后面所有“读取设计稿”的操作都是只读的不会污染你在 Figma 里的原始文件。但“修改类”操作建议在副本上先跑通一遍再应用到主文件血泪教训别问我是怎么知道的。1.3 技术选型为什么非要选 MCP 而不是写死 API项目最开始我也想过更直接的方案——写死调用 Figma REST API 的函数给 Agent 配上工具描述不就行了吗但真正动手后发现不是那么回事。Agent 的核心能力是理解和规划它需要一个稳定的、带语义的工具接口。如果你直接丢给它一堆 REST API 文档它也能猜着调用但每次对话都会消耗大量 token而且很容易写出奇奇怪怪的路径参数。MCPModel Context Protocol的价值在于它把工具定义、输入 schema、返回结构都标准化了Agent 只需要认识一组“方法名”和“参数含义”剩下的信息熵值全部被封装在协议里。而且 MCP 还天然自带“资源”概念。我们不只是给 Agent 几个方法调用还可以把设计稿的关键节点暴露成资源和 prompt 模板Agent 在进入工作状态前可以先自动找回当前设计稿的上下文再决定调用哪些工具。另一个重要原因是MCP Server 是独立进程和 Agent 客户端完全解耦。这意味着统一套工具既能给本地桌面端 Agent 用也能接到云端 Agent 服务上未来还能让团队共享同一套 bridge 能力。这种架构典型的“一次建设、到处接入”。2. 技术原理与核心架构拆解2.1 MCP 协议在 Agent 与 Figma 链路中的角色MCP 这个名字可能很多前端同学还不太熟它全称 Model Context Protocol通俗讲就是“给 AI 用的 USB-C 接口”。USB-C 统一了硬件设备的充电和数据协议MCP 则统一了 AI 应用与外部工具、数据源之间的通信协议。现在我们接数据库有 database MCP接文件系统有 filesystem MCP接 Figma 自然也要有 figma MCP。MCP 的通信模型分三个角色Host比如 Claude Desktop、Cursor 这类 Agent 客户端它负责调度对话和调用工具。Client在 Host 内部负责与某个 MCP Server 建立连接。Server暴露工具、资源和提示词实际执行业务逻辑。我们的 FAB 就是一个 Server它内部封装了与 Figma 相关的所有能力对外暴露成 tools。Agent 要读取设计稿就调用get_file_nodes要导出图片就调用get_image要执行修改就调用apply_plugin_action。每个工具都有清晰的入参和出参描述Agent 只需要根据用户需求自动组合这些工具。2.2 Figma REST API 读取能力拆解Figma 官方提供的 REST API目前正式版里读取能力是最成熟的。这正好满足了 Agent 的第一步需求“看懂设计稿”。常用端点就几个端点用途关键参数GET /v1/files/:key获取整个文件的结构file keyGET /v1/files/:key/nodes获取指定节点及子节点ids、geometry 等GET /v1/images/:key导出节点为图片ids、format、scaleGET /v1/comments/:key读取设计稿评论file key这里有个比较容易踩坑的点Figma API 返回的节点数据非常详细包含name、type、absoluteBoundingBox、fills、characters、styles这些字段。如果不加限制地全部返回一份复杂设计稿的 JSON 可能几 MB 甚至几十 MBAgent 的上下文窗口根本吃不消。所以我们的 MCP Server 里做了三层裁剪按页面裁剪先列出所有页面让用户明确要操作哪个页面。按深度裁剪只返回与目标操作相关的图层层级比如改文本就返回到文本节点层不需要背景图层的所有外框坐标。按属性裁剪默认只返回语义字段比如文本内容、颜色、字号、间距坐标数据在需要时再逐一加载。这一步非常关键直接影响 Agent 的效率和准确度。很多做了 MCP 集成但效果差的项目十有八九是栽在返回数据太大、Agent 看不过来。2.3 Bridge 插件在 Figma 内部执行修改操作上面说到Figma REST API 的写能力很有限。官方目前公开的 REST API 里可执行写操作的主要是评论、文件操作相关。而改图层属性、改文本、调整布局正规渠道是通过Figma Plugin API在客户端内部操作。因此我们的方案里加了一个桥接插件叫figma-bridge-plugin。它运行在 Figma 桌面端里会做的事非常简单监听本机 WebSocket 消息MCP Server 将 Agent 的计划指令转发给插件插件调用 Figma Plugin API 完成真正的修改。整体链路长这样Agent 请求 ↓ MCP Server (figma-agent-bridge) ↓ 经 MCP 协议调用 modify_design 工具 MCP Server 通过 WebSocket 转发 ↓ Figma 内的 Bridge Plugin ↓ 调用 Plugin API 修改文本 / 调整样式 / 移动组件 / 导出图片为什么要用 WebSocket 而不是直接走 REST API因为 Figma 插件运行在客户端内它没有公网 IPREST API 无法主动访问它。WebSocket 是长连接MCP Server 作为 Server 端插件作为 Client 端建立隧道后MCP Server 就能主动向插件下发指令。这个方案和现在很多自动化测试工具的桥接思路一致。注意这个设计从安全角度讲是可控的。插件只监听本机 WebSocket 端口端口上我默认加了随机 token不是随便谁能连上。你甚至可以配置成只允许本机回环地址访问外界完全不可见。2.4 数据链路与权限边界因为 FAB 既要读又要写权限模型就得分开设计读取权限通过 Figma Access Token 访问 REST API。这个 Token 建议使用只读权限file content:readonly专门给 MCP Server 用。写权限通过 Bridge Plugin 执行。插件权限由你在 Figma 客户端里手动授权并且只能在当前打开的文档里操作。这样的好处是即使 Access Token 不小心泄露了别人也只能读你的文件不能改。写操作始终控制在已经打开 Figma、并运行了 Bridge 插件的机器上。对团队协作来说这是个很务实的安全隔离方案。3. 本地环境搭建与配置实操3.1 准备一个支持 MCP 的 Agent 客户端这一步很简单。目前主流的 Agent 客户端基本都支持 MCP 配置了我用的是 Claude Desktop 和 Cursor实测都能正常接入。你选哪个不重要关键是确认它能加载本地 MCP Server。如果你还没装我给两条建议Claude Desktop适合把 FAB 当成 AI 设计助手来用对话界面更友好适合设计师体验。Cursor适合开发场景改完设计稿马上能关联到代码对前端舒服。另外FAB 本身依赖 Node.js 18所以本地要先装好 Node。这些是基础中的基础我就不啰嗦了。3.2 获取 Figma Access TokenFigma Access Token 是 MCP Server 访问 REST API 的凭证。获取路径如下登录 Figma 网页版进入个人设置页面。在Security选项下找到Personal access tokens。点Generate new token权限范围里勾选File content: Read-only和Comments: Read-only就够了。生成后立即复制保存因为 Figma 只会显示这一次。然后你需要拿到目标设计稿的 File Key。打开设计稿的 URL格式一般是https://www.figma.com/design/{fileKey}/{title}中间的fileKey就是后续所有 API 调用的核心参数。3.3 对接 Bridge 插件为了让 Agent 能执行“修改”操作你还得把 Bridge 插件装到 Figma 客户端里。做法如下在 FAB 项目的plugin/目录下找到manifest.json。打开 Figma 桌面端进入菜单里的Plugins Development Import plugin from manifest。选中该manifest.json插件就会出现在开发插件列表里。点击运行该插件插件窗口里会显示一个 WebSocket 连接状态显示connected就代表已经和本地 MCP Server 握手成功。这里有个小坑插件必须在包含目标设计稿的文件里运行如果你切换到了别的文件Agent 的修改就会落在错的画布上。后面我会在排查章节展开。3.4 MCP 配置文件写法接下来就是把 FAB 注册到 Agent 客户端。以 Claude Desktop 为例在配置文件claude_desktop_config.json里添加{ mcpServers: { figma-bridge: { command: npx, args: [-y, figma-agent-bridge], env: { FIGMA_ACCESS_TOKEN: 你的只读token, BRIDGE_PORT: 8765, BRIDGE_TOKEN: 本机通信随机token } } } }如果是 Cursor在项目根目录创建.cursor/mcp.json写法大同小异。配置完成后重启 Agent 客户端然后在对话里问一句“帮我读取当前设计稿的总览”如果 Agent 返回了设计稿页面列表就说明整条链路已经通了。4. 核心功能实现与场景演示4.1 场景一读取设计稿结构让 Agent“看懂”页面链路通了以后我们先做一个只读操作验验成果。我拿一个电商 App 的首页设计稿做测试输入指令如下请读取当前设计稿的总览列出首页的全部主要区块并概括每个区块的用途。Agent 收到指令后会先调用list_pages拿到首页这个 page 的 id再调用get_file_nodes用我们裁剪过的数据结构列出几个关键 Frame 名称像Header、Banner、ProductGrid、TabBar之类。然后 Agent 会自然整合这些信息给出一个清晰的页面层级总结。实测下来对一个有 300 多个节点的中等复杂度页面Agent 从调用工具到给出总结大约 10 秒左右。对设计师来说这相当于多了一个“先帮我看图”的 AI 助理。4.2 场景二修改文本内容和颜色只读只是开胃菜写操作才是这个项目的重头戏。注意这一步需要先确保 Bridge 插件已经在 Figma 内连接成功。现在我对 Agent 说把首页主 Banner 的标题文本改成“春季焕新”并把标题颜色改为一个更鲜明的橙色品牌色那套橙色就行。Agent 的执行过程是这样的调用读取工具定位到主 Banner 对应的 Frame拿到里面文本节点的nodeId。解析当前文本内容和填充颜色。生成一个修改计划比如{ action: set_text, nodeId: 112:334, chars: 春季焕新 }。通过 MCP Server 转发给 Bridge 插件插件在 Figma 内部执行修改。最后调用get_image导出该区块截图让用户确认效果。这里面最有价值的是第 3 步——Agent 不是盲目发指令而是先理解节点结构再决定改哪个属性。这依赖我们在 MCP Server 里对节点做了语义化命名。比如文本节点如果没有命名我们会自动生成一个关联父 Frame 的名称方便 Agent 理解。实操心得在设计稿里给图层定期做命名规范整理能显著提升 Agent 的输出准确率。我们实验下来规范命名后Agent 第一次就选中正确节点的概率从约 65% 升到了 92% 以上。4.3 场景三批量调整间距与对齐很多设计系统都定义了统一的间距变量比如4 / 8 / 12 / 16 / 24。但实际设计稿里总有图层不按变量走而这个擦屁股的活非常适合交给 Agent。我给 Agent 的指令是检查商品卡片区域中所有元素之间的间距把不满足 8px 间距规范的统一调整为 8px但保持整体布局不变。Agent 会读取ProductGridFrame 下所有子节点的absoluteBoundingBox计算出两两之间当前间距找出不满足规范的那些然后生成一组“移动节点”指令通过插件批量执行。这个操作如果手动做至少需要 10 分钟而 Agent 大约 30 秒就能完成。而且它还能顺手生成一份“修改报告”列出改了哪些节点、原来的间距和现在的间距各是多少。这对有强迫症的团队简直是救星。4.4 场景四导出多尺寸切图以往的切图流程是设计完手动切 1x 和 2x 图再导出到目录。FAB 里只需要对 Agent 说把登录页卡片区域分别导出为 1x 和 2x 的 PNG保存到项目的 assets/login/ 目录下。Agent 会调用get_image接口设置scale1和scale2把图片抓下来直接写入指定目录。这个过程对前端同学特别友好等于省掉了“设计师导出后放到共享盘开发再从共享盘下载”的环节。4.5 在设计团队中落地的协作模式建议工具做出来是给人用的项目跑通后我也在团队里试了试真实工作流。最后沉淀下来一套比较顺的模式批量改稿需求集中下来时产品先用自然语言描述所有改动点Agent 统一处理最后设计师检查一遍。这时候 Agent 是“执行者”。风格统一巡检每两周让 Agent 自动扫一遍设计稿检查字体、颜色、间距是否与设计 token 一致输出不符合项。这时候 Agent 是“质检员”。设计和开发对齐开发需要某个切图时自己向 Agent 要不打断设计师。这时候 Agent 是“传话员”。当然不建议让 Agent 在新页面创意设计的阶段直接动手因为那一阶段强调的是探索和发散Agent 的调度式操作反而会限制思考。Agent 最适合的是重复性、规则明确、有客观验收标准的那类改动。5. 常见问题与排查技巧实录5.1 Figma Token 权限不足读取时报 403这是我自己最开始踩的坑。第一次生成 Token 时为了省事权限范围选少了结果调用get_file_nodes时 Figma 直接返回 403。排查时第一反应是看 MCP Server 的日志发现日志里明确写的是Insufficient permission这才意识到是 Token 权限问题。解决办法就是回 Figma 重新生成 Token勾上File content: Read-only。建议每次生成 Token 后先用 curl 手测一下curl -H X-Figma-Token: 你的token https://api.figma.com/v1/me能返回用户信息说明 Token 基本有效再进一步测文件接口确认权限。5.2 MCP 服务启动成功但 Agent 报工具找不到这类问题九成是 MCP Server 启动顺序或配置路径的问题。先确认配置里的command和args是否拼写正确再确认npx是否在 PATH 里。还有一个隐蔽问题如果你是在某个项目目录里启动 Agent 客户端MCP 配置读的是全局配置还是项目配置不同客户端行为不一样。我的建议是先在全局配置里注册跑通后再决定要不要下沉到项目级配置。实操心得每次改完 MCP 配置必须完全退出 Agent 客户端再重启热重载不是所有客户端都支持。我一开始指望“改完立刻生效”结果浪费了整整一个下午。5.3 Agent 拿到设计稿数据后“看不过来”这个前面提过本质是返回数据太庞大。如果你自己实现的 MCP Server 直接把整份文件 JSON 丢给 Agent很快就会发现 Agent 回答开始答非所问甚至直接报超时。解决办法就是在 Server 端做裁剪和摘要先只返回页面层级再由 Agent 决定深入哪个页面。属性里默认去掉absoluteBoundingBox之外不常用的几何字段。对长文本内容做截断。这样既保证了交互速度也大幅降低了 token 消耗。想省钱的团队这步一定要做。5.4 修改不生效Bridge 插件已经连接但节点没动静该做的操作都做了插件也连接上了但 Figma 里的元素纹丝不动。我遇到过两种典型情况插件权限锁定了。Figma 插件在读取时默认允许访问当前页面但写操作需要你在插件代码中显式调用figma.currentPage去选择正确页面。如果你 MCP 指令里给了某个 nodeId但当前页面里没有这个节点插件就会静默失败。处理方式是让 Agent 在修改前先通过get_file_nodes验证一次 nodeId 是否确实属于当前页面。图层被锁定或隐藏。Figma 里允许锁定某个图层锁定后插件 API 修改不会生效。这属于典型的“肉眼看不出来”的问题排查时可以检查节点属性里是否有locked: true。另外Figma 插件里改成文本后必须调用一次figma.notify或者手动触发一下重绘否则界面可能没有实时刷新。这个在插件代码里加上即可。5.5 设计稿复杂度过高Agent 执行时间过长遇到超大型设计稿上千个节点Agent 的规划和调用链会变得特别长。我建议两条优化路径拆分任务让 Agent 先读总览再按区块逐个处理不要指望一条指令解决所有问题。降低节点返回深度在对布局做批量处理时只返回 Frame 层级的包围盒数据不需要每个 fill 属性的细节。这两个改动听起来不复杂但实测能把整个任务时间缩短一半以上。这也再次说明Agent 类工具能不能发挥价值很关键的基础是外围工具链适配得够不够务实。5.6 多文件场景别把文件切换忘了最后说一个特别容易混乱的场景。一个 Figma 账号下同时打开了多个文件Bridge 插件只会运行在当前激活的那个文件里。如果 Agent 读取的是文件 A但 Figma 客户端当前打开的是文件 B修改操作就会落在 B 或者在 A 上找不到节点而失败。我的团队在 workflow 里强制加了一个校验Agent 在执行任何写操作前先调用 Bridge 插件的get_current_file_key方法确认当前激活文件的 key 与目标文件一致后才继续执行。这一点写进插件简单可靠。6. 个人心得与未来扩展这次开源项目的经历让我重新审视了一遍“Agent 改变工作流”这件事。很多人把 Agent 想象成“全能 AI 替身”但实际跑下来它更像一个执行力很强的实习生你给它足够清晰的环境、工具和反馈机制它能交出不错的成绩但如果你让它面对混乱的数据结构和不明不白的流程它就容易卡壳。所以我做这类 Agent 工具最大的心得是外围基建决定 Agent 的上限而不是模型本身。MCP Server 里的数据裁剪和语义化工作比我在模型层做的 prompt 调优重要得多。这也解释了为什么同一个模型接不同 MCP Server效果天差地别。回到 FAB 这个项目它未来还有几个方向可以扩展。一个是接入设计 token 校验自动检查设计稿与设计系统的偏差另一个是支持组件级操作像“更新所有页面的按钮组件实例”这种这需要更精细的插件权限管理。最后分享一个真实的细节我把 FAB 项目推到 GitHub 上之后收到的第一个 star 是一个外国设计师留的他在 README 底下留言说“这玩意终于让我不用在凌晨三点因为改字号被叫醒了。”看到那条评论的时候我确实有点感触——技术工具做出来如果在某个具体场景里真的让人少熬一次夜那就值了。