Local Figma Agent MCP：让AI编程助手直接读写Figma设计稿

1. 这个插件到底解决了什么问题设计稿和代码之间的那道墙做过前端或者全栈的人应该都深有体会。产品经理在 Figma 里画完原型设计师调整了十几版间距和颜色最后落到开发手里要么是截图加标注要么是导出切图加手动测量。一个按钮的圆角从 8px 改成 12px你得打开设计稿、选中元素、看右侧面板、再回到代码里改。如果一天改二十次心态直接崩。Local Figma Agent MCP 这个插件核心思路就是让 AI 编程助手直接“看见”Figma 文件里的结构并且能够对设计稿执行修改操作。注意这里有两个关键词读懂和修改。读懂意味着 Agent 能获取到图层树、样式属性、组件关系、自动布局参数这些结构化数据修改意味着它不只是只读还能反过来调整设计稿里的节点属性比如改颜色、调间距、替换文本、移动位置。为什么这件事值得单独拿出来说因为 Figma 官方的 REST API 虽然功能强大但有几个现实门槛。第一部分能力需要付费套餐才能使用比如某些团队级别的 API 访问权限。第二官方 API 的调用需要处理认证、分页、速率限制对于只是想快速让 Agent 帮忙改个设计稿的场景来说链路太长。第三很多开发者手里只有个人免费版账号想做一些自动化实验官方路径走不通。Local Figma Agent MCP 走的是另一条路它通过本地运行一个轻量服务利用 Figma 桌面端或者浏览器端的本地调试能力把设计稿的数据暴露给 Agent。你可以把它理解成在 Figma 和 AI 助手之间架了一座本地桥数据不出本机不需要额外的付费订阅也不需要把设计文件上传到第三方服务器。适合谁来用如果你满足下面任意一条这个方案就值得花时间折腾一下日常用 AI 编程助手写前端代码希望它能直接读取设计稿里的样式和结构减少手动对照手里只有 Figma 免费账号但想尝试设计稿自动化的玩法做设计系统维护需要批量检查或修改组件库里的样式一致性对 MCP 协议感兴趣想找一个真实可跑的案例来理解 Agent 工具调用的完整链路不适合谁如果你期望的是完全零配置、点一下就能用、并且对稳定性要求极高比如生产环境批量操作那本地方案会有一些折腾成本需要你有基本的命令行操作能力和排查问题的耐心。2. 核心原理拆解MCP 协议和本地桥接是怎么配合的2.1 MCP 协议到底在做什么MCP 全称是 Model Context Protocol翻译过来叫模型上下文协议。你可以把它想象成 AI 助手和外部工具之间的一个“标准插座”。以前每个 AI 工具想调用外部能力都得自己定义一套接口规范A 工具用 JSON-RPCB 工具用 RESTC 工具用 WebSocket乱得很。MCP 做的事情就是统一这个插槽的形状工具端按照 MCP 规范暴露自己的能力Agent 端按照 MCP 规范去发现和调用这些能力。具体到 Local Figma Agent MCP它暴露给 Agent 的能力通常包括这几类读取类工具获取当前选中的节点、获取指定节点的属性、获取页面结构树、获取样式变量写入类工具修改节点属性填充色、描边、圆角、透明度、调整自动布局参数、替换文本内容、创建或删除节点查询类工具按名称搜索图层、按类型筛选节点、获取组件实例信息Agent 在收到你的自然语言指令后会先判断需要调用哪个工具然后通过 MCP 协议发送请求本地服务收到请求后转发给 Figma 插件端执行执行结果再原路返回。整个过程对你来说就是一句话的事但底层走了“自然语言 → 工具选择 → 参数构造 → 本地执行 → 结果回传”这条链路。2.2 为什么是“本地”而不是“云端”这里要重点说一下本地运行的意义。云端方案通常需要你把 Figma 文件通过 OAuth 授权给第三方服务然后第三方服务调用官方 API 来读写。这个路径的问题在于你的设计文件数据会经过第三方服务器对于涉及未发布产品、商业机密的设计稿来说很多团队是不接受的。另外云端服务往往有调用次数限制免费额度用完后就得付费。本地方案的数据流向完全不同Figma 插件运行在你的浏览器或桌面端里本地 MCP 服务运行在你的电脑上Agent 也运行在你的电脑上。三者之间的通信走的是 localhost数据不出本机。这意味着没有额外的网络延迟没有第三方服务器的隐私风险也没有按次计费的压力。当然代价也有你需要自己启动服务、自己维护运行环境、自己处理版本兼容问题。但对于开发者来说这些成本是可控的而且换来的是完全自主的控制权。2.3 插件端和服务端的分工整个架构可以拆成三个角色Figma 插件端负责和 Figma 编辑器交互。它运行在 Figma 的插件沙箱环境里能够访问当前打开文件的节点树能够执行修改操作。插件端通过 WebSocket 或者本地 HTTP 连接把能力暴露出去。本地 MCP 服务端负责协议转换。它接收 Agent 发来的 MCP 请求翻译成插件端能理解的指令再把结果包装成 MCP 响应格式返回。这个服务通常是一个 Node.js 进程跑在 localhost 的某个端口上。Agent 端就是你的 AI 编程助手它内置了 MCP 客户端能力能够发现本地服务暴露的工具列表并根据对话上下文决定调用哪个工具、传什么参数。三者之间的时序大致是这样的你在 Agent 对话框里输入“把当前选中的矩形填充色改成 #FF6B35”Agent 解析意图后调用 MCP 工具的set_node_fill本地服务收到请求后通过 WebSocket 发给 Figma 插件插件在编辑器里执行修改然后把执行结果逐层返回。你看到的就是 Agent 回复“已完成选中矩形的填充色已更新”。3. 环境准备与插件安装实操3.1 前置条件检查在动手之前先把下面这几项确认一遍缺一个后面都可能卡住Figma 账号免费版即可不需要 Professional 或 Organization 套餐。这是这个方案最大的优势之一。Figma 桌面端或浏览器推荐用桌面端插件运行更稳定本地连接不容易断。浏览器端也可以用但要注意不要频繁刷新页面。Node.js 环境版本建议 18 以上因为很多 MCP 相关的依赖包对 Node 版本有要求。用node -v检查一下如果低于 18先去升级。AI 编程助手需要支持 MCP 协议。目前主流的一些代码助手已经陆续支持自定义 MCP 服务配置具体看你用的工具是否开放了这个能力。基本的命令行操作能力需要会运行npm install、npm start这类命令遇到报错能看懂大致意思。注意整个方案不涉及任何需要特殊网络环境的内容所有依赖都通过正常的包管理渠道获取。如果安装过程中遇到网络超时检查一下 npm 源配置即可。3.2 获取插件和本地服务代码Local Figma Agent MCP 通常以开源项目的形式发布包含两部分Figma 插件代码和本地 MCP 服务代码。获取方式一般是从代码托管平台克隆仓库到本地。克隆完成后目录结构大致是这样的local-figma-agent-mcp/ ├── plugin/ # Figma 插件端代码 │ ├── manifest.json │ ├── code.js │ └── ui.html ├── server/ # 本地 MCP 服务端代码 │ ├── package.json │ ├── index.js │ └── tools/ └── README.md先进入 server 目录安装依赖cd local-figma-agent-mcp/server npm install安装完成后先别急着启动检查一下 package.json 里的启动脚本和端口配置。通常默认端口是 3000 或者 3847 这类不常用的端口避免和你本机其他服务冲突。3.3 在 Figma 中加载插件Figma 加载本地插件的方式是“开发模式加载”。具体步骤打开 Figma 桌面端进入任意一个设计文件在顶部菜单找到 Plugins → Development → Import plugin from manifest选择你克隆下来的 plugin 目录里的 manifest.json 文件导入成功后在 Plugins → Development 下面就能看到这个插件运行插件后Figma 右侧会弹出一个插件面板面板里通常会显示连接状态。如果本地服务还没启动状态会显示“未连接”启动服务后状态会变成“已连接”。实操心得第一次加载插件后建议把 Figma 文件保存一下。有些情况下插件在未保存的文件里运行会有限制。另外如果你同时开了多个 Figma 标签页确保插件运行在你当前操作的那个文件里否则 Agent 读到的可能是另一个文件的数据。3.4 启动本地 MCP 服务回到命令行在 server 目录下启动服务npm start如果一切正常你会看到类似这样的输出MCP server running on port 3847 WebSocket server ready for Figma plugin connection Available tools: get_selection, get_node, set_fill, set_text, ...这时候回到 Figma 插件面板连接状态应该变成已连接。如果还是未连接检查一下端口是否被占用或者防火墙是否拦截了本地回环连接。3.5 配置 Agent 端的 MCP 服务这一步取决于你用的 AI 编程助手。通常需要在配置文件中添加一个 MCP 服务条目指定服务地址和端口。配置格式大概是这样的{ mcpServers: { local-figma-agent: { url: http://localhost:3847/mcp, description: Local Figma design agent } } }配置完成后重启 Agent它应该能自动发现这个 MCP 服务暴露的工具列表。你可以在 Agent 对话框里问它“你现在有哪些 Figma 相关的工具可以用”如果配置正确它会列出读取和修改设计稿的能力。4. 核心功能实操让 Agent 真正读懂设计稿4.1 读取选中节点的完整属性先做最简单的验证在 Figma 里选中一个矩形然后在 Agent 对话框里输入“帮我看看当前选中的这个节点有哪些属性”。Agent 会调用get_selection工具返回的数据通常包括节点 ID、名称、类型位置和尺寸x, y, width, height填充色可能是十六进制值或 RGBA描边属性颜色、粗细、对齐方式圆角半径透明度自动布局参数如果是 Frame文本内容如果是 Text 节点这个能力看起来简单但实际用起来很省事。以前你要手动去右侧面板一个个看现在直接问一句就行。而且 Agent 可以把这些属性整理成 CSS 或者 Tailwind 类的形式直接贴到代码里。4.2 批量读取页面结构如果你想让 Agent 了解整个页面的布局可以选中一个 Frame然后让它“读取这个 Frame 下面所有子节点的结构”。返回的是一棵层级树Agent 会把它整理成可读的缩进列表。这个能力在做页面还原的时候特别有用你可以把整棵结构树丢给 Agent让它生成对应的 HTML 结构或者 React 组件骨架。注意如果页面节点特别多比如几百个图层一次性读取可能会返回很大的数据量导致 Agent 处理超时。建议先读取顶层结构确认层级后再逐个子树深入。我在一个包含 300 多个节点的页面里试过全量读取Agent 直接卡住了后来改成按 Frame 分批读取就顺畅了。4.3 修改填充色和描边这是“修改”能力的核心场景。选中一个节点然后告诉 Agent“把填充色改成 #4A90D9描边改成 2px 的 #333333”。Agent 会依次调用set_fill和set_stroke工具。执行成功后Figma 画布上的节点会立即更新。你可以肉眼看到颜色变化不需要手动操作。这里有一个细节值得说颜色格式的转换。Figma 内部用的是 0-1 范围的 RGBA 浮点数而我们在对话里习惯用十六进制。MCP 服务端需要做这个转换。如果转换逻辑有 bug可能会出现颜色偏差。实测下来大部分开源实现都会正确处理这个转换但如果你发现颜色不对优先检查这一块。4.4 调整自动布局参数自动布局是 Figma 里最常用的功能之一但手动调间距和方向也挺繁琐。通过 Agent 可以直接说“把这个 Frame 的自动布局改成垂直方向间距 16px内边距上下 24px 左右 32px”。Agent 会调用对应的工具修改layoutMode、itemSpacing、paddingTop等属性。这个能力在做响应式调整的时候特别高效你可以让 Agent 一次性把一组 Frame 的布局参数统一改掉不用一个个手动调。4.5 替换文本内容选中一个 Text 节点告诉 Agent“把这段文字替换成‘欢迎回来请登录你的账户’”。Agent 调用set_text工具完成替换。这个场景在本地化或者文案调整时很实用。你可以批量选中多个 Text 节点让 Agent 按照规则统一替换。比如把所有按钮文案里的“提交”改成“确认”或者把占位符文本统一替换成正式文案。4.6 创建新节点部分实现还支持创建节点。你可以让 Agent“在这个 Frame 里创建一个 200x48 的矩形填充色 #007AFF圆角 8px”。Agent 会调用创建工具在指定位置生成节点。这个能力目前在不同实现里支持程度不一样有的只支持创建基础形状有的支持创建组件实例。用之前先确认一下你的版本支持哪些创建操作。5. 常见问题与排查技巧实录5.1 连接类问题插件显示未连接但服务已经启动先检查端口是否一致。插件端和服务端的端口配置要匹配有时候插件默认连 3000但服务端跑在 3847就会连不上。其次检查是否有多个服务实例在跑导致端口冲突。用lsof -i :端口号看一下占用情况。还有一个容易忽略的点如果你用的是浏览器版 Figma某些浏览器安全策略可能会拦截 localhost 的 WebSocket 连接。换成桌面端通常能解决。连接时断时续这种情况多半是 Figma 插件被挂起了。Figma 为了节省资源在插件面板不可见时会暂停插件运行。保持插件面板可见或者定期点一下画布可以让连接保持活跃。5.2 数据读取类问题Agent 读到的属性不完整不同节点类型暴露的属性不一样。比如 Group 节点没有填充色属性Text 节点有字体相关属性。如果你发现某些属性缺失先确认节点类型是否匹配。另外有些实现只返回显式设置的属性继承自组件的属性可能不在返回结果里。读取大文件时超时前面提过节点数量太多会导致数据量爆炸。解决办法是分批读取或者只读取你真正需要的子树。也可以在 MCP 服务端配置里调整超时时间但根本办法还是减少单次请求的数据量。5.3 修改类问题修改没有生效先确认选中的节点是否被锁定。锁定的节点无法修改Agent 调用工具时会返回错误。其次检查节点是否在组件内部有些实现不允许直接修改组件内部的节点需要先 detach 或者进入组件编辑模式。修改后样式被覆盖如果节点应用了样式Style或者绑定了变量Variable直接修改属性可能会被样式覆盖。这种情况下需要先解除样式绑定或者直接修改样式定义本身。Agent 通常能识别这种情况并给出提示但你需要决定是改实例还是改样式源。5.4 性能与稳定性问题操作延迟明显本地方案的延迟主要来自两个环节Agent 的推理时间和 Figma 插件的执行时间。推理时间取决于你的 Agent 配置和当前负载执行时间通常很快。如果感觉整体很慢先看 Agent 那边的响应速度再看 Figma 插件面板有没有卡顿。批量操作时部分失败批量修改多个节点时如果其中一个失败后续操作可能会中断。建议在 Agent 指令里明确“跳过失败项继续执行”或者在 MCP 服务端实现错误隔离。我在批量改 50 个节点颜色的时候遇到过一次中间失败导致后面全没执行的情况后来改成每 10 个一组分批执行就稳定了。5.5 常见问题速查表问题现象可能原因排查方向插件显示未连接端口不一致或服务未启动检查端口配置确认服务进程存在连接频繁断开插件面板被挂起保持面板可见避免切换标签页读取属性缺失节点类型不支持该属性确认节点类型检查是否继承自组件修改不生效节点被锁定或绑定样式解锁节点解除样式绑定批量操作中断单个节点执行失败分批执行增加错误隔离颜色偏差色彩空间转换问题检查十六进制到 RGBA 的转换逻辑6. 进阶玩法与扩展思路6.1 设计稿转代码的完整链路把 Local Figma Agent MCP 和代码生成能力结合起来可以搭一条从设计稿到代码的自动化链路。具体做法是先用读取工具获取选中 Frame 的完整结构树和样式属性然后让 Agent 根据这些数据生成对应的组件代码。这里的关键在于数据格式的整理。Agent 拿到的是 Figma 的节点树需要把它映射成代码里的 DOM 结构或者组件树。你可以给 Agent 一些映射规则比如 Frame 对应 divAuto Layout 对应 flex 布局Text 对应 span 或 p。实测下来对于结构规整的设计稿生成的代码骨架能省掉 70% 以上的手写时间。6.2 设计系统一致性检查如果你维护着一个组件库可以用这个方案做批量检查。比如让 Agent 遍历某个页面下所有按钮组件检查它们的圆角是否都是 8px、填充色是否都在允许的色板范围内。发现不一致的节点可以直接让 Agent 修正。这个玩法在团队协作场景下特别有价值。设计师改了一版组件开发还没同步用 Agent 跑一遍检查就能快速发现偏差。6.3 批量文案替换与本地化多语言项目里文案替换是个体力活。通过 MCP 的文本修改能力你可以准备一份映射表让 Agent 按照映射表批量替换设计稿里的文案。比如把中文版设计稿里的所有文案替换成英文生成一份英文版设计稿。这个过程中要注意文本长度变化导致的布局问题。英文通常比中文长替换后可能会出现文字溢出。建议替换后让 Agent 检查一遍文本容器的尺寸必要时调整自动布局参数。6.4 与版本管理结合设计稿的修改历史在 Figma 里有版本记录但不够细粒度。你可以用这个方案做一个简单的变更日志每次 Agent 执行修改操作后把操作类型、目标节点、修改前后的值记录到一个本地文件里。这样回溯的时候能清楚看到谁在什么时候改了什么。实现方式是在 MCP 服务端加一个日志中间件拦截所有写入类工具的调用把参数和结果写进日志文件。这个改动不大但长期来看很实用。7. 一些实操后的个人体会这个方案我断断续续用了几个月最大的感受是它把“设计稿操作”这件事从手动变成了对话式。以前改一个组件的样式要选中、找属性、输入数值、确认现在一句话就搞定。特别是批量操作的时候效率提升非常明显。但也要客观说本地方案的稳定性确实不如成熟的商业产品。偶尔会遇到连接断开、插件无响应、数据读取不全的情况。我的应对策略是重要操作前先手动保存 Figma 文件批量操作分批执行遇到异常先重启服务和插件。这套流程跑熟之后大部分问题都能在几分钟内解决。另外一点体会是Agent 对设计稿的理解能力取决于你给它的上下文。如果你只说“改一下这个按钮”它可能不知道你指的是哪个按钮。但如果你说“把当前选中的这个圆角矩形按钮的填充色改成蓝色”它就能准确执行。所以指令的明确程度直接决定了执行效果这一点和写代码时的注释是一个道理。还有一个容易被忽略的点Figma 的插件沙箱环境对某些 API 有限制。比如跨文件操作、访问团队库资源在插件里可能做不了。遇到这种情况要么换用官方 API 补充要么调整需求范围。本地方案不是万能的它解决的是“单文件内读写”这个最高频的场景更复杂的跨文件协作还是得走官方渠道。最后分享一个小技巧如果你经常需要读取同一类节点的属性可以在 MCP 服务端加一个自定义工具把常用的查询逻辑封装进去。比如“获取当前页面所有按钮组件的样式摘要”这样 Agent 调用一次就能拿到整理好的数据不用多次往返。这个扩展不难做但能省不少事。