1. 项目概述当AI智能体学会“看”设计稿最近在折腾一个挺有意思的东西让AI智能体比如Cursor、Claude Code能直接和Figma对话。听起来有点科幻其实原理不复杂就是通过一个叫Model Context ProtocolMCP的协议给AI装上了一双能“看见”和“操作”Figma设计稿的眼睛和手。这个项目的核心价值在于它把设计稿从一个静态的、需要人工解读的“图片”变成了一个AI可以直接读取、理解甚至修改的“结构化数据源”。想象一下你不再需要手动截图、标注、向开发解释设计意图AI可以直接读取Figma文件理解图层结构、间距规范、组件关系然后根据你的指令生成代码、修改设计或者自动完成一些重复性的设计任务。这不仅仅是效率的提升更是工作流的一次重构。我花了些时间深入研究并实践了这个cursor-talk-to-figma-mcp项目。它本质上是一个桥梁由三部分组成一个运行在你本地的MCP服务器用TypeScript写的一个需要安装在Figma里的插件以及一个负责两者通信的WebSocket服务器。下面我就把自己从环境搭建、功能实践到深度应用过程中积累的经验和踩过的坑系统地分享给你。2. 核心架构与通信原理拆解在开始动手之前理解这套系统是如何工作的至关重要。这能帮助你在遇到问题时快速定位而不是盲目操作。2.1 三方角色与数据流整个系统的协作关系可以清晰地用以下流程来描述AI智能体如Cursor作为指令的发起者。当你在Cursor的聊天框中输入“把首页标题改成‘欢迎登录’”时Cursor会解析这个指令。MCP服务器作为AI的“外挂大脑”。Cursor通过MCP协议调用我们部署的TalkToFigma服务器提供的工具例如set_text_content。这个服务器是用Bun运行的一个Node.js程序。WebSocket服务器作为实时消息中转站。MCP服务器并不直接连接Figma而是将指令封装成特定格式的消息通过WebSocket发送出去。Figma插件作为在Figma内部的“执行器”。插件订阅了WebSocket服务器的频道。当它收到来自MCP服务器的消息后就调用Figma Plugin API执行真正的操作比如选中某个文本图层并修改其内容。结果返回操作完成后插件会将结果成功或失败信息通过WebSocket原路返回给MCP服务器再经由MCP协议反馈给Cursor最终呈现在你面前。关键理解Figma插件是必须的因为Figma本身的安全策略不允许外部程序直接操作其内部数据。所有操作都必须通过官方认可的插件体系来完成。这个项目中的插件就是一个“授权代理”。2.2 为什么选择MCP你可能会问为什么不用简单的HTTP APIMCP是Anthropic提出的一种标准协议旨在为AI模型提供安全、可控的工具调用能力。它的优势在于标准化提供了一套统一的工具定义、调用和结果返回格式。这意味着为Cursor写的MCP服务器稍作调整也能服务于其他支持MCP的AI助手。声明式工具描述每个工具如get_document_info都有清晰的输入、输出描述AI能更好地理解何时以及如何使用它。安全性工具运行在本地或你信任的服务器上数据不出域避免了敏感设计资产上传到第三方云服务的风险。这套架构决定了安装过程必须三步走启动通信枢纽WebSocket、为AI配置工具MCP、在Figma内安装执行终端插件缺一不可。3. 从零开始的完整安装与配置指南网上很多教程一步带过但实际安装中90%的问题都出在环境配置和步骤遗漏上。我结合在macOS和Windows WSL下的实测给你一个保姆级流程。3.1 基础环境准备Bun是关键项目使用Bun作为运行时它比Node.js启动更快且内置了包管理、测试运行器非常适合这种工具类项目。# 安装BunUnix/macOS/Linux curl -fsSL https://bun.sh/install | bash # 安装后重启终端或运行 source ~/.zshrc (或 ~/.bashrc) # 验证安装 bun --version对于Windows用户最稳定的方案是使用WSL2Windows Subsystem for Linux。在WSL的Ubuntu终端里用上面的命令安装Bun即可。不推荐在PowerShell中直接安装Bun的Windows版本因为后续的路径和脚本兼容性问题会很多。3.2 获取项目并安装依赖# 克隆项目代码 git clone https://github.com/grab/cursor-talk-to-figma-mcp.git cd cursor-talk-to-figma-mcp # 使用项目自带的setup脚本安装依赖并配置Cursor MCP bun run setup这个bun setup命令非常关键它做了两件事安装项目所有的TypeScript依赖bun install。自动尝试在Cursor的全局MCP配置中注册本服务器。它会检查或创建~/.cursor/mcp.json文件并添加一个指向本项目的配置项。安装完成后务必检查一下~/.cursor/mcp.json文件内容应该类似这样{ mcpServers: { TalkToFigma: { command: bun, args: [/你的绝对路径/cursor-talk-to-figma-mcp/src/talk_to_figma_mcp/server.ts] } } }实操心得如果bun setup后Cursor依然找不到工具大概率是路径问题。手动检查并编辑mcp.json确保args中的路径是绝对路径并且指向server.ts文件。相对路径在Cursor的上下文中可能无法正确解析。3.3 启动WebSocket服务器这是通信的桥梁需要保持运行状态。# 在项目根目录下启动WebSocket服务器 bun run socket如果一切正常终端会显示服务器已启动在某个端口例如ws://localhost:3001。请保持这个终端窗口打开。3.4 安装并连接Figma插件这是最容易出错的一步。安装插件推荐直接从Figma社区安装。在Figma中点击左侧菜单栏的Plugins-Community搜索“cursor talk to figma mcp plugin”并安装。这是最省事的方法。开发模式如果你想自己修改插件代码可以在Figma中选择Plugins-Development-New plugin-Link existing plugin然后选择项目中的src/cursor_mcp_plugin/manifest.json文件。连接插件在Figma中打开任意设计文件。再次打开Plugins-Development-cursor-talk-to-figma-mcp-plugin。插件UI界面会出现。在“Channel”输入框里输入一个频道名例如my-design-session然后点击Join Channel。如果连接成功插件界面会显示“Connected”状态并且你之前启动WebSocket服务器的终端里应该会看到类似[INFO] Client joined channel: my-design-session的连接日志。踩坑记录连接失败按这个顺序排查① WebSocket服务器 (bun socket) 是否在运行② 频道名是否输入一致大小写敏感③ 如果你在公司网络是否有防火墙阻止了WebSocket连接通常是3001端口可以尝试在本地简单测试。3.5 Windows WSL 特别注意事项如果你在Windows上使用WSL需要额外一步配置让FigmaWindows应用能连接到WSL子系统Linux环境中运行的WebSocket服务器。找到项目中的src/socket.ts文件。找到创建WebSocket服务器的部分大概在第30行左右你会看到类似下面的代码被注释了// uncomment this to allow connections in windows wsl // hostname: 0.0.0.0,取消这行的注释让它变成hostname: 0.0.0.0,保存文件并重启bun socket服务。这个改动让服务器监听所有网络接口而不仅仅是WSL内部的localhost这样Windows主机上的Figma才能访问到它。4. 核心功能实战与高阶技巧配置好了我们来真正用起来。下面我通过几个典型场景带你深入理解每个工具的价值和最佳实践。4.1 场景一AI快速读取设计稿信息这是最基础也最常用的功能。以前你需要对着设计稿向AI描述现在AI自己会“看”。操作流程在Figma中用插件加入一个频道如my-project。在Cursor中直接提问“当前Figma画布上有什么” 或 “给我看看选中的元素信息”。Cursor会自动调用get_document_info或get_selection工具并将结果以结构化的方式返回给你。返回的信息示例简化文档名称: 用户仪表盘 v2.3 当前页面: Home Page 选中元素: [Frame] “用户信息卡片” (id: 2:15) 尺寸: 360x200 位置: (x: 120, y: 80) 子元素: 1个头像 (Rectangle), 2个文本层高阶技巧read_my_design的妙用read_my_design是一个更强大的工具它不需要参数直接返回当前选中元素的详细递归信息。当你选中一个Frame时它能把这个Frame里所有嵌套的子图层、文本内容、样式属性都扒出来。这对于让AI全面理解一个复杂组件的构成极其有用。注意事项对于非常大的画布或极其复杂的组件一次性读取所有信息可能会返回海量数据导致AI上下文窗口压力过大。此时更佳的策略是先用get_document_info了解全局再用get_node_info针对特定ID的节点进行精细查询。4.2 场景二批量文本内容替换效率飞跃这是社区贡献的一个杀手级功能。假设你的设计稿里有几十个地方写着“旧产品名”需要全部改成“新产品名”。手动找眼要瞎。让AI来做的正确姿势指令“将当前页面中所有包含‘旧产品名’的文本替换为‘新产品名’。”AI的执行逻辑调用scan_text_nodes。这个工具非常智能如果页面文本节点太多它会自动分块chunk扫描避免数据过大。分析返回的文本节点列表筛选出characters属性包含“旧产品名”的节点并记录它们的id。调用set_multiple_text_contents工具传入一个数组一次性将所有需要修改的节点ID和新内容提交。结果Figma画布上所有相关文本瞬间更新。实操心得精准定位你可以让AI替换“仅限主画板Frame内”或“排除组件实例”的文本这需要结合get_node_info来获取节点的层级路径信息让AI做逻辑判断。样式保留使用set_text_content系列工具修改内容不会影响文本的字体、颜色、大小等样式属性只会改变文字本身非常安全。风险控制在执行大批量替换前可以先用scan_text_nodes看看会影响到哪些节点做到心中有数。或者先在一个小范围如一个Frame内进行测试。4.3 场景三组件实例覆写Propagation的魔法这是另一个来自社区的强大贡献。在Figma中当你有一个按钮组件Component并创建了它的多个实例Instance后如果想统一修改其中几个实例的某个属性比如图标颜色传统做法是逐个修改。而这个功能可以“复制粘贴”覆写。操作流程在Figma中手动调整好一个“源实例”Source Instance的所有属性颜色、文本、图标等。选中这个调好的源实例。在Cursor中告诉AI“获取当前选中实例的覆写属性。”AI调用get_instance_overrides会得到一个结构化的属性列表例如{primary/Icon: #FF0000, primary/Text: 提交}。在Figma中框选其他你想要应用同样修改的“目标实例”Target Instances。回到Cursor告诉AI“将刚才获取的覆写属性应用到当前选中的实例上。”AI调用set_instance_overrides一键完成批量同步。这个功能的精妙之处在于它操作的是Figma底层的、可被程序识别的“覆写属性”而不是简单的像素拷贝。这意味着修改是精准的、可逆的并且保持了与主组件的链接关系。4.4 场景四将原型连线转换为FigJam连接线可视化流这个功能对于需要将交互原型文档化的场景非常有用。Figma的“原型”功能可以创建页面跳转连线Reactions但它们在设计模式下是隐藏的。这个工具能将其可视化。提取原型流让AI调用get_reactions。它会返回一个包含所有交互连接信息的列表包括起点节点、终点节点、交互类型等。设置连接线样式在FigJam文件中或设计文件的某个角落画一条你喜欢的箭头连接线设置好颜色、粗细、箭头样式。选中它然后让AI调用set_default_connector。这个操作会“记住”这条连接线的样式。批量生成最后让AI调用create_connections并传入第一步获取的reactions数据。AI会自动在起点和终点节点之间按照你预设的样式创建清晰的FigJam连接线。结果你得到了一张可视化的用户流程图清晰地展示了所有页面跳转关系这对于评审和开发交接非常有价值。5. 开发、调试与故障排查实录如果你不满足于使用还想自己修改或贡献代码或者遇到了问题这部分是你的救命稻草。5.1 本地开发模式配置如果你想修改MCP服务器的逻辑比如增加一个新工具修改src/talk_to_figma_mcp/目录下的代码。更新本地的Cursor MCP配置 (~/.cursor/mcp.json)确保它指向你本地的开发服务器文件。{ mcpServers: { TalkToFigma: { command: bun, args: [/ABSOLUTE/PATH/TO/YOUR/REPO/src/talk_to_figma_mcp/server.ts] } } }重启Cursor。Cursor通常只在启动时读取MCP配置修改后必须重启才能生效。保持bun socket运行并在Figma中重新连接插件。5.2 修改Figma插件如果你想调整插件端的UI或逻辑修改src/cursor_mcp_plugin/code.js或ui.html。在Figma中进入Plugins-Development。找到cursor-talk-to-figma-mcp-plugin旁边会有一个刷新图标↻点击它来重新加载插件。通常不需要重启Figma。5.3 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案Cursor中不显示Figma相关工具1. MCP配置错误2. Cursor未重启3. Bun服务未运行1. 检查~/.cursor/mcp.json路径是否正确、文件是否存在。2.完全关闭并重启Cursor。3. 在项目根目录运行bun socket并确保无报错。Figma插件显示“连接失败”1. WebSocket服务器未启动2. 频道名不匹配3. 防火墙/网络问题4. (WSL) 未配置hostname: “0.0.0.0”1. 确认终端中bun socket正在运行。2. 检查插件和AI指令中的频道名是否完全一致。3. 尝试在浏览器访问http://localhost:3001(如果服务器提供测试页)。4. WSL用户检查socket.ts配置。工具调用后无反应或报错1. Figma中未选中元素2. 节点ID已失效3. 插件未连接4. 指令参数错误1. 确保Figma中有正确的选中元素。2. 切换页面或修改文件后旧的节点ID会失效需重新获取。3. 确认插件UI显示“Connected”。4. 让AI使用get_selection先看看当前状态。批量操作超时或部分失败1. 操作节点过多2. 网络波动3. Figma API限制1. 对于超大规模操作尝试分批次进行。2. 检查WebSocket终端是否有错误日志。3. Figma插件API有调用频率限制工具内部已做队列处理但极大量操作仍需耐心。Windows下Bun命令未找到在PowerShell中安装但WSL中未安装确保在WSL终端内安装Bun所有操作都在WSL环境下进行。5.4 调试技巧查看“幕后”通信当工具调用出现诡异问题时最有效的调试方法是查看通信日志。查看WebSocket服务器日志运行bun socket的终端会打印所有连接、消息接收和发送的记录。这是第一手信息。查看Cursor的MCP日志Cursor的设置中可能有更详细的MCP调试输出选项可以查看工具调用请求和原始响应。简化复现用一个最简单的操作如get_selection测试整个链路是否通畅逐步排除问题。6. 最佳实践与安全考量经过一段时间的深度使用我总结出一些能让这个工作流更顺畅、更安全的经验。6.1 操作流程上的最佳实践始终先“Join Channel”这是所有操作的先决条件就像打电话要先拨号。先读后写先查后改在执行任何修改操作前先用get_document_info、get_selection或get_node_info确认你操作的对象是正确的。AI很强大但让它盲目操作是危险的。善用“撤销”和历史版本Figma强大的撤销Cmd/CtrlZ和历史版本功能是你的安全网。在进行大规模自动化修改前可以手动保存一个版本快照。分而治之处理大型文件对于超大型设计文件不要试图一次性扫描所有节点。通过指定特定的页面Page或顶级框架FrameID来限定操作范围。组件化思维鼓励AI多使用create_component_instance和覆写功能。保持设计的系统性便于后续维护和批量更新。6.2 安全与数据隐私这是一个本地优先Local-First的方案这是它最大的优点之一数据不出境所有通信Cursor - MCP Server - WebSocket - Figma Plugin都发生在你的本地机器或内部网络原始设计文件永远不会被发送到外部AI服务商如OpenAI、Anthropic的服务器。权限可控Figma插件需要你明确授权才能访问当前打开的文件。它无法访问你没有打开的文件。理解AI的上下文需要注意的是当你使用Cursor或Claude等AI时你与AI的对话内容以及AI从Figma读取到的设计信息如图层名称、文本内容会作为对话上下文发送给对应的AI服务提供商例如OpenAI的服务器。这是AI服务的工作原理。因此请避免将高度敏感或机密的设计信息通过对话方式暴露。对于敏感项目这是一个重要的考量点。6.3 性能与稳定性优化保持依赖更新定期git pull拉取项目更新并运行bun install更新依赖以获取性能优化和Bug修复。管理Bun进程如果长时间不使用可以考虑停止bun socket进程以节省资源。需要时再启动。清晰的频道管理不同的项目或设计文件可以使用不同的频道名如project-alphaproject-beta进行隔离避免指令错乱。这个项目的意义远不止于“又一个自动化工具”。它代表了一种趋势设计工具正在从封闭的、面向人的图形界面演变为开放的、面向机器AI的API平台。作为设计师或开发者掌握如何让AI成为你设计流程中的“协作者”而不仅仅是“执行者”将是未来的一项重要技能。从自动替换文案、同步组件样式到生成设计规范文档、检查设计系统一致性可能性才刚刚被打开。我个人的体会是最大的障碍往往不是技术而是我们是否愿意重新思考既有的工作流并勇敢地迈出尝试的第一步。