1. 项目概述当AI智能体学会“看图说话”如果你和我一样既是开发者又经常需要和设计师打交道那你一定经历过这样的场景设计师在Figma里更新了一个按钮样式或者调整了某个页面的布局然后你需要手动去代码里找到对应的组件小心翼翼地修改样式值生怕一个像素的偏差破坏了整个视觉和谐。又或者产品经理丢过来一份满是标注的Figma设计稿你需要花上半天时间像玩“大家来找茬”一样把文字内容、间距、颜色一个个核对并更新到你的原型或文档里。这个过程不仅枯燥、重复而且极易出错。设计师和开发者之间仿佛隔着一道无形的墙一边是直观的视觉设计另一边是精确的代码逻辑。有没有一种方式能让我们的AI助手——比如我们每天都在用的Cursor或者Claude——直接“看懂”Figma设计稿并且能按照我们的指令去修改它呢这就是cursor-talk-to-figma-mcp这个项目要解决的问题。它不是一个简单的API封装而是一座建立在Model Context Protocol之上的桥梁。MCP你可以理解为AI智能体Agent的“标准外设接口协议”。通过它AI智能体可以安全、结构化地访问和使用各种外部工具和数据源。而这个项目就是为AI智能体装上了“Figma操作手柄”。简单来说它包含三个核心部分一个MCP服务器运行在你的本地或服务器上作为AI智能体Cursor/Claude和Figma之间的翻译官和指令分发中心。一个Figma插件安装在你的Figma设计文件中负责接收来自MCP服务器的指令并在Figma内部执行具体的操作比如选中元素、修改文本、调整样式。一个WebSocket服务器作为MCP服务器和Figma插件之间的实时通信管道确保指令和反馈能够快速、双向流动。想象一下这个工作流你在Cursor的聊天框里输入“把首页Banner的所有‘立即体验’按钮文字改成‘免费试用’颜色改成品牌蓝色#0066FF。” Cursor理解你的意图后通过MCP调用这个项目的工具指令经由WebSocket发送给Figma插件几秒钟内Figma画板上的所有相关按钮就自动完成了更新。而你全程没有手动点击过一次Figma界面。这不仅仅是自动化这是让AI成为了你在设计工具中的“数字双手”将自然语言指令直接转化为设计变更。接下来我将带你从零开始拆解这个项目的部署、核心原理以及如何最大化利用它来提升你的设计开发协作效率。2. 核心原理与架构拆解在深入实操之前我们有必要理解这套系统是如何运转的。知其然更要知其所以然这样在遇到问题时你才能快速定位甚至根据自己的需求进行定制。2.1 Model Context ProtocolAI的“外设”总线MCP的核心思想是标准化AI智能体与外部资源的交互方式。在没有MCP之前每个AI工具想要连接Figma、数据库或命令行都需要自己实现一套复杂的适配逻辑这就像每台电脑都要为不同的打印机专门编写驱动一样低效。MCP定义了一套标准的“工具”描述格式。一个MCP服务器Server可以向AI智能体Client宣告“我这里提供了get_document_info、create_rectangle等工具这是它们的名字、描述、参数格式和返回值。” AI智能体只需要按照这个标准格式去调用即可无需关心底层是Figma API、Slack API还是一个本地脚本。为什么选择MCP而不是直接调用Figma API安全性MCP服务器运行在本地你的Figma访问令牌Token不会泄露给云端AI服务。AI智能体只与本地MCP服务器通信由MCP服务器负责与Figma API的安全交互。能力抽象Figma REST API功能庞大且复杂。MCP服务器可以对API进行封装和简化提供更符合设计操作语义的工具如set_layout_mode降低AI智能体的理解和使用门槛。状态管理MCP服务器可以维护会话状态例如当前连接的Figma文件、WebSocket通道等AI智能体无需关心这些底层连接细节。2.2 三方协作的通信链路整个系统的数据流是一个清晰的三角关系[AI智能体 (Cursor/Claude)] --(MCP协议)-- [本地MCP服务器] --(WebSocket)-- [Figma插件] --(Figma Plugin API)-- [Figma设计文件]指令下发你在AI智能体界面发出指令 - AI智能体解析意图选择并调用MCP工具如set_multiple_text_contents- 调用请求被发送到本地MCP服务器。指令路由MCP服务器收到请求它并不直接操作Figma。而是将指令和参数打包通过之前建立好的WebSocket连接发送给正在某个Figma文件里运行的Figma插件。指令执行Figma插件收到指令利用Figma官方提供的Plugin API在当前的Figma文档上下文中执行具体操作比如找到某个节点ID修改其文字内容。结果回传操作执行完成后Figma插件将结果成功或失败信息、可能的新节点数据通过WebSocket发回给MCP服务器MCP服务器再按照MCP格式包装后返回给AI智能体。界面反馈最终AI智能体会以对话形式告诉你操作结果。同时你可以在Figma界面实时看到元素被修改的视觉反馈。WebSocket的关键作用为什么不用简单的HTTP请求因为设计操作往往是连续、交互式的。WebSocket提供了全双工、低延迟的持久连接非常适合这种需要实时传递指令和状态更新的场景。例如批量修改上百个文本节点时插件可以通过WebSocket流式地返回进度让AI智能体和你都能知道任务进行到哪一步了。2.3 项目结构深度解析查看项目源码我们能更清楚地看到职责划分src/talk_to_figma_mcp/这是MCP服务器的核心。它用TypeScript编写利用modelcontextprotocol/sdk创建服务器并定义了我们在上一章看到的几十个工具Tools。每个工具函数内部主要逻辑是验证参数、通过WebSocket客户端向插件发送消息、等待并处理插件的响应。src/cursor_mcp_plugin/这是Figma插件的源代码。包含code.js插件主逻辑、ui.html插件面板界面和manifest.json插件配置文件。它的核心是监听来自WebSocket的特定格式消息调用figma全局对象提供的方法如figma.currentPage.selection,figma.getNodeById(id)来执行UI操作然后将结果发送回去。src/socket.ts一个基于bun和ws库的轻量级WebSocket服务器。它管理客户端MCP服务器和插件端的连接并实现了一个简单的“频道”机制允许多个插件实例连接到同一个服务器上的不同频道避免指令串扰。这种架构的优势在于解耦。MCP服务器不依赖Figma环境可以独立运行和测试。Figma插件只负责UI操作逻辑单一。任何一部分都可以单独升级或替换。3. 从零开始的完整部署与配置指南理论讲完我们动手把它跑起来。我会以macOS/Linux环境为主进行说明并在最后补充Windows/WSL的特别注意事项。3.1 基础环境准备首先你需要一个Figma账号和一个可编辑的设计文件。接着在本地安装运行环境。1. 安装 Bun 运行时这个项目选择Bun作为JavaScript运行时因为它启动快、内置了包管理器和测试运行器非常适合工具类项目。# 使用官方安装脚本 curl -fsSL https://bun.sh/install | bash安装完成后重启你的终端运行bun --version确认安装成功。2. 获取项目代码# 克隆仓库到本地 git clone https://github.com/grab/cursor-talk-to-figma-mcp.git cd cursor-talk-to-figma-mcp3. 安装项目依赖项目根目录下的setup脚本实际是bun install的封装会安装所有依赖并尝试帮你配置Cursor的MCP。# 运行安装脚本 bun setup注意bun setup脚本可能会尝试修改你的~/.cursor/mcp.json文件。如果自动配置失败不用担心我们后面会手动配置。3.2 启动通信枢纽WebSocket服务器WebSocket服务器是MCP服务器和Figma插件之间的桥梁必须先启动它。# 在项目根目录下执行 bun socket如果一切正常终端会输出类似WebSocket server is running on ws://localhost:3001的信息。请保持这个终端窗口一直运行。3.3 安装与激活Figma插件你有两种方式安装插件方式一从Figma社区安装推荐最简单打开Figma桌面应用或网页版。在顶部菜单栏选择PluginsCommunity。在搜索框中输入 “cursor talk to figma mcp plugin” 或直接访问项目文档中提供的社区链接。找到插件后点击Install。方式二本地开发模式安装用于自定义开发在Figma中进入PluginsDevelopmentNew Plugin。选择Link existing plugin。在弹出的文件选择器中导航到你克隆的项目目录选择src/cursor_mcp_plugin/manifest.json文件。插件就会出现在你的Development插件列表里。激活插件并连接打开你想要操作的那个Figma设计文件。再次进入PluginsDevelopment找到并点击你刚刚安装的“Cursor MCP Plugin”。插件面板会打开。你需要告诉它连接到我们刚才启动的WebSocket服务器。在插件面板的输入框里输入命令join_channel my_design_session频道名可以自定义比如用项目名然后点击发送或按回车。如果连接成功插件面板会显示连接状态并且bun socket的终端里也会出现新的连接日志。3.4 配置AI智能体以Cursor为例现在需要让Cursor知道我们的MCP服务器在哪里。1. 定位或创建MCP配置文件Cursor的MCP配置文件通常位于~/.cursor/mcp.jsonmacOS/Linux或%USERPROFILE%\.cursor\mcp.jsonWindows。如果文件不存在就创建一个。2. 编辑配置文件用你喜欢的文本编辑器打开这个文件。你需要添加一个指向本地MCP服务器的配置。这里有两种方式方式A使用全局安装的包推荐更稳定如果你之前成功运行了bun setup它可能已经配置好了。如果没有手动添加如下内容。这假设你通过bunx从网络运行最新版本的服务器。{ mcpServers: { TalkToFigma: { command: bunx, args: [cursor-talk-to-figma-mcplatest] } } }方式B指向本地开发目录用于调试或修改代码如果你想运行自己修改过的源码需要指向本地的服务器入口文件。{ mcpServers: { TalkToFigma: { command: bun, args: [/绝对路径/到/cursor-talk-to-figma-mcp/src/talk_to_figma_mcp/server.ts] } } }重要提示必须使用Bun的绝对路径。你可以通过which bun命令找到它。同时确保路径中的.ts文件存在。3. 重启Cursor保存mcp.json文件后完全关闭并重新启动Cursor。这是必须的步骤因为Cursor只在启动时读取MCP配置。4. 验证连接重启后在Cursor里新建一个聊天。如果你在输入框下方或者侧边栏的工具列表里看到了新增的工具比如get_document_info或者尝试问AI“你能使用Figma工具吗”它回答是肯定的那就说明配置成功了。3.5 Windows WSL 用户特别指南如果你在Windows上使用WSLWindows Subsystem for Linux进行开发需要额外的网络配置因为WSL的localhost与Windows宿主机的localhost不完全互通。安装Bun在WSL终端内使用同样的curl命令安装Bun即可。修改WebSocket服务器主机名打开src/socket.ts文件找到创建WebSocket服务器的部分。你会看到类似hostname: localhost的配置。为了允许来自Windows主机Figma应用的连接你需要将其改为// 取消这行的注释或将其修改为 0.0.0.0 hostname: 0.0.0.0,这会使服务器监听所有网络接口。获取WSL的IP地址在WSL终端运行hostname -I记下输出的IP地址通常是172.x.x.x这样的格式。连接Figma插件在Figma插件面板中join_channel命令需要指定完整的WS地址。例如join_channel ws://WSL_IP:3001 my_channel。其中WSL_IP替换为你上一步获得的地址。配置Cursor如果你的Cursor安装在Windows主机上而MCP服务器运行在WSL你需要在Windows的mcp.json配置中将command指向WSL内的Bun。这比较复杂更简单的方法是直接在Windows主机上安装Bun并运行整个项目或者使用方式Abunx配置这通常能更好地处理跨系统调用。4. 核心工具详解与实战应用现在系统已经就绪。我们来深入看看这些MCP工具能做什么以及如何在实际工作中运用它们。我会将工具分为几大类并结合典型场景进行说明。4.1 信息获取与导航先“看清”再操作任何自动化操作的前提都是精准定位。这类工具是你的“眼睛”。get_document_info: 这是你的第一步。它返回当前Figma文件的元信息包括页面列表、组件集等。在你不知道从何下手时先用它看看文件结构。get_selection: 获取当前你在Figma画布上选中的节点ID和基本信息。非常有用你可以先在Figma里手动框选一组元素然后让AI基于这个选择进行操作。read_my_design/get_node_info: 这两个是深度信息获取工具。read_my_design会对当前选中的节点进行“解读”返回其类型、尺寸、位置、样式、子节点等详细信息甚至包括文本内容。get_node_info则需要你提供具体的节点ID功能类似。当AI需要理解一个按钮的精确颜色、字体大小时就会调用它们。实战场景生成设计标注文档你可以对AI说“请读取当前选中的这个卡片组件的详细信息并以为开发同学编写标注文档的格式输出。” AI会调用get_selection和get_node_info获取到间距、颜色、字体等数据然后生成一份结构清晰的Markdown标注文档。4.2 内容修改与批量处理告别重复劳动这是最能体现效率提升的部分尤其是文本内容的批量更新。scan_text_nodes: 这是一个“扫描器”。对于大型设计稿直接获取所有文本节点可能超时或数据量过大。这个工具允许你分块chunk扫描。你可以指定从第几个节点开始扫描一次扫描多少个。AI可以循环调用它逐步获取整个页面的所有文本内容。set_text_content/set_multiple_text_contents: 前者修改单个文本节点后者批量修改。批量修改是核心效率工具。它的参数是一个数组每个元素包含nodeId和新的characters文本内容。实战场景多语言文案替换假设你有一个为英文市场设计的产品原型现在需要快速制作中文版。你准备好一个JSON映射文件如{Sign Up: 注册, Login: 登录, ...}。你可以将文件内容粘贴给AI并指令“请扫描当前页面的所有文本节点并根据我提供的映射表将英文文案替换为中文。”AI会先调用scan_text_nodes获取所有文本节点及其ID和内容。然后AI在内存中进行匹配和替换组装成一个set_multiple_text_contents所需的参数数组。最后一次性调用批量更新工具。几十上百个文本节点在几秒内全部更新完毕。避坑指南批量更新时务必注意文本节点的nodeId必须准确。scan_text_nodes返回的节点信息里就包含ID。如果设计稿中有很多重复的、未命名的文本图层建议先让AI建议你为关键节点命名或使用get_selection进行确认避免改错对象。4.3 组件与样式管理保持设计系统一致性对于使用设计系统的团队组件实例和样式是核心资产。get_local_components/get_styles: 探查当前文件中定义了哪些可复用的组件和样式颜色、文本、效果等。create_component_instance: 基于已有的主组件创建一个实例。你可以指定放置的位置x, y坐标。get_instance_overrides/set_instance_overrides: 这是项目贡献者dusskapark带来的强大功能。实例覆盖传播是Figma中一个常见但繁琐的操作你精心调整了一个组件实例比如改了图标和文字现在需要把同样的调整应用到另外十个相同的实例上。get_instance_overrides: 从你调整好的那个“源实例”中提取出所有被覆盖的属性如某个子图层的填充色、某个文本图层的字符。set_instance_overrides: 将提取出的覆盖属性精确地应用到其他“目标实例”上。AI可以帮你选中所有需要同步的实例然后批量完成这个操作。实战场景设计走查与批量修复设计师发现某个按钮组件的内边距padding需要从16px调整为20px。他修改了主组件。你告诉AI“找到当前页面中所有使用了‘Button/Primary’这个主组件的实例并将它们同步到最新版本。”AI需要先get_local_components找到该组件再遍历页面节点找到所有实例这可能需要组合其他工具或策略然后理论上应该有一个“同步到主组件”的工具当前工具集未直接提供但可通过其他方式组合实现。这个场景展示了未来工具扩展的方向。4.4 自动布局与样式调整精细化控制这类工具让你能通过代码精确控制Figma的自动布局和视觉属性。set_layout_mode: 设置一个Frame的布局方向水平、垂直、无。set_padding,set_item_spacing,set_axis_align等工具则用于微调布局参数。set_fill_color,set_stroke_color,set_corner_radius: 直接修改节点的填充色、描边和圆角。参数需要遵循Figma的RGBA格式{r: 0, g: 0.4, b: 1, a: 1}。实战场景响应式布局调整你有一个卡片列表当前是垂直排列。产品希望在大屏上能水平排列。 你可以指令AI“选中ID为‘card-list’的Frame将其布局模式改为水平HORIZONTAL子项间距设置为24像素并让子项在主轴primary axis上居中对齐。” AI会依次或组合调用set_layout_mode,set_item_spacing,set_axis_align来完成。4.5 高级功能标注、原型与导出标注Annotationsset_annotation和set_multiple_annotations可以让你以编程方式添加Figma原生标注。这对于自动化生成设计评审意见、将外部需求导入为画布标注非常有用。原型连线Connectionsget_reactions可以提取Figma原型中的交互连线那些“面条”。结合set_default_connector和create_connections可以将这些交互流可视化为FigJam风格的连接线生成更清晰的用户流程图。导出export_node_as_image可以将某个节点导出为图片。虽然当前返回的是Base64文本但AI可以将其保存为文件或用于生成报告。5. 最佳实践、排错与效能提升经过一段时间的实际使用我总结出一些能让你事半功倍、并避开常见陷阱的经验。5.1 稳定高效的工作流连接顺序是关键务必遵循启动WebSocket服务器-在Figma中打开插件并join_channel-重启Cursor使MCP配置生效的顺序。任何一步错乱都可能导致连接失败。会话开始先“摸底”开始操作前先让AI使用get_document_info和get_selection了解当前上下文。这能避免很多“对象不存在”的错误。善用批量操作对于文本替换、样式应用、覆盖同步等操作尽量使用set_multiple_text_contents、set_multiple_annotations等批量工具。这比循环调用单次工具快一个数量级也减少了网络往返和出错概率。ID是唯一凭证Figma中的节点ID是稳定且唯一的。在编写脚本或进行复杂操作时依赖节点名称name不如依赖ID可靠因为名称可能重复或更改。get_selection和scan类工具返回的结果中都包含ID请妥善保存和使用它们。分治大型文件对于节点数量巨大超过500个的设计稿直接扫描全部节点可能会超时。利用scan_text_nodes的chunkSize和startIndex参数进行分块处理。让AI编写一个简单的循环逻辑来逐步获取所有数据。5.2 常见问题与排查手册问题现象可能原因排查步骤与解决方案Cursor中看不到Figma工具1. MCP配置错误2. Cursor未重启1. 检查~/.cursor/mcp.json格式是否正确路径是否存在。2.完全关闭并重启Cursor。这是最常被忽略的一步。插件面板显示“未连接”或连接失败1. WebSocket服务器未运行2. 频道名错误/冲突3. 网络/防火墙问题WSL常见1. 确认bun socket终端正在运行且无报错。2. 确认插件中输入的join_channel命令格式正确如join_channel my_session。3. WSL用户检查hostname是否为0.0.0.0并使用WSL IP连接。AI调用工具后长时间无反应或报超时错误1. Figma插件未响应2. 操作过于复杂耗时3. WebSocket连接中断1. 检查Figma插件面板是否有错误信息。2. 对于复杂操作尝试拆分成更小的步骤。3. 在插件面板重新发送join_channel命令重连。工具执行失败返回“Node not found”1. 节点ID错误或已失效2. 操作了其他页面的节点1. 使用get_selection重新获取目标节点的正确ID。2. 确保你操作的节点在当前激活的页面Page上。Figma插件API通常只对当前页有效。批量修改文本时部分节点未生效1. 文本节点被锁定Locked2. 节点在组件实例内且该属性未被允许覆盖1. 在Figma中手动检查并解锁图层。2. 对于组件实例需要主组件先“暴露”该文本属性为可覆盖。export_node_as_image返回乱码或失败当前功能限制该功能目前可能不稳定或返回Base64数据格式有误。建议优先使用Figma内置导出或通过Figma API的其他方式导出。5.3 效能提升技巧组合使用工具与AI提示词Prompts项目中内置了一些MCP Prompts如text_replacement_strategy、swap_overrides_instances。在Cursor中你可以直接让AI“使用text_replacement_strategy提示词”它会引导你完成一个系统性的文本替换流程包括扫描、确认、替换、验证等步骤非常适合新手。利用AI进行条件判断你可以给AI更复杂的指令。例如“扫描当前页面所有文本找出所有字号小于12px的文本节点并把它们的颜色改为红色以作警示。” AI需要先调用scan_text_nodes然后分析返回数据中的style.fontSize筛选出符合条件的节点ID最后组装set_fill_color的调用参数。本地化与自定义如果你团队有特殊的组件规范或操作流程完全可以fork这个项目在src/talk_to_figma_mcp/server.ts中添加自定义的工具。例如添加一个sync_to_design_system工具自动将画板中的颜色和文本样式与团队的设计系统库进行比对和提示。与版本控制结合虽然不能直接回滚Figma操作但你可以让AI在重大修改前先用get_document_info和get_node_info将关键节点的状态以JSON格式备份下来。如果需要恢复可以编写一个反向操作的工具这需要一定的开发工作。这个项目的真正威力在于它将Figma从一个纯图形界面工具变成了一个可以通过自然语言和逻辑进行编程操作的“设计数据库”。它打破了设计和开发之间的工具壁垒让设计资产的维护、批量更新和规范检查变得前所未有的高效和准确。从简单的文案替换到复杂的组件实例管理你现在可以坐在Cursor的聊天窗口前用几句话就完成以前需要大量重复点击的工作。