Claude Talk to Figma MCP：让 AI 设计师真正「长出手」

想象这样一个场景：产品经理给你一个 200 页的 Figma 设计稿，要求把所有主色调从蓝色换成橙色、把字号统一调大两号、按钮样式全部改为圆角——传统做法需要设计师手工逐个修改 200×N 个元素，或者用笨拙的 Figma 插件批量替换。而现在，你可以直接对 AI 说：「把这个设计里所有主色调换成橙色，所有按钮改为圆角」，AI 就会在 Figma 里忠实执行——这正是 Claude Talk to Figma MCP 正在做的事。

图1：Claude Talk to Figma MCP 工作全景——AI 通过 MCP 协议直接操控 Figma 设计文件

一、项目背景：为什么需要「AI 操控 Figma」？

Figma 是当前最主流的 UI/UX 设计协作工具，全球设计师用它完成了无数产品的视觉设计。然而，Figma 和代码世界之间始终隔着一道鸿沟：设计师在 Figma 里画好 UI，工程师要在代码里重新实现，两边的命名、结构、对齐方式往往不一致，每次「设计交付」都伴随着大量的沟通摩擦。

随着 Claude、Cursor、Windsurf 等 AI 编程工具的崛起，一个新的需求浮出水面：能否让 AI 直接理解、读取、甚至修改 Figma 设计稿？答案是肯定的——但前提是要有一套标准协议，让 AI 工具能够「说 Figma 的语言」。

Model Context Protocol（MCP） 就是这个标准协议。它由 Anthropic 提出，目标是成为「AI 工具的 USB 接口」——无论你用哪个 AI 客户端，只要实现了 MCP，就能连接任何支持 MCP 的服务。Figma 官方提供了 MCP 协议支持，但有一个限制：需要开通 Dev Mode 许可证（收费功能）。

这给了开源社区一个切入机会。Claude Talk to Figma MCP 的作者 Xúlio Zé 选择了一条不同的路线：不依赖 Figma 官方 Dev Mode，而是通过 WebSocket + Figma Plugin 的组合，让任何拥有 Figma 账号（免费账号即可）的用户，都能用 AI 操控自己的设计稿。

图2：在 Cursor 中配置 Claude Talk to Figma MCP 的步骤——只需在 mcp.json 中添加服务器配置

二、核心原理：三层架构如何「借道」Figma

这套 MCP 的技术架构值得深入拆解。它本质上是一个双通道通信系统，由三个核心层组成。

第一层：MCP Server（TypeScript + Bun）

这是 MCP 协议的服务端，基于 @modelcontextprotocol/sdk 实现。MCP Server 通过 stdio 传输层与 AI 客户端通信，接收来自 AI 的工具调用请求（如 create_rectangle、set_fill_color、get_node_info），然后将命令转发给下一层。Server 本身不直接操作 Figma，它是一个命令路由中枢。

MCP Server 注册了 10 大类工具（见 tools/index.ts）：

• 文档工具（document-tools）：get_document_info、get_pages、get_selection、get_node_info
• 创建工具（creation-tools）：create_rectangle、create_frame、create_text、create_ellipse、create_polygon 等
• 修改工具（modification-tools）：set_fill_color、set_stroke_color、set_text_content、resize_node 等
• 组件工具（component-tools）：get_components、get_component_sets
• 图片工具（image-tools）：get_image_fill、get_image_hash
• SVG 工具（svg-tools）：get_svg、set_svg
• 样式工具（style-tools）：set_effect、set_opacity、set_blend_mode
• 变量工具（variable-tools）：get_variables、set_variable
• 文本工具（text-tools）：set_text_content、set_font_family、set_font_size
• FigJam 工具（figjam-tools）：create_sticky、create_connector、create_shape_with_text

每个工具都使用 Zod 做 Schema 校验（coerceJson 包装器），确保 AI 传入的参数类型安全。

第二层：WebSocket 服务器（Bun）

这是整个系统的「通信总线」——一个运行在 3055 端口的轻量 WebSocket 服务器（src/socket.ts，31KB），使用 Bun 原生的 bun:server 实现。相比 Node.js 的 ws 库，Bun 的内置 WebSocket 性能更优、内存占用更低。

WebSocket Server 的核心职责是多客户端路由：

• Figma Plugin 客户端：运行在用户本机 Figma Desktop 中的插件，与 Figma 本地 API 通信
• Agent 客户端：即 MCP Server，作为中间人将 AI 请求转发到 Figma

Server 实现了完整的命令队列机制（channelQueues）：

• 每个 channel（由 channel ID 标识）维护一个 FIFO 队列
• 队列最大深度 100，超过时拒绝新命令（queueRejections 统计）
• 每个命令超时 120 秒，防止插件挂死导致死锁
• 响应按 request ID 精确路由回发起请求的 Agent（requestToClient Map）

这是一个典型的生产消费者模式：Agent 发命令 → 队列缓冲 → Plugin 消费 → 响应路由回 Agent。Session 去重机制（sessionToClient Map）确保同一 AI 会话重连时，旧的陈旧连接被清理，防止路由混乱。

第三层：Figma Plugin（嵌入 Figma Desktop）

这是真正「长出手」的部分。Plugin（src/claude_mcp_plugin/）以 HTML + JS 的形式加载到 Figma Desktop 中，承担两个职责：

1. 接收来自 WebSocket Server 的 Figma API 命令
2. 调用 Figma Desktop Plugin API 执行实际操作
3. 将执行结果通过 WebSocket 推送回 Agent

Plugin 通过 manifest.json 注册，无需 Figma 官方授权，完全依赖 Figma Desktop Plugin API，这也是为什么任何免费账号都能用的原因。

图3：配置完成后，AI 可以直接「看到」Figma 文件内容并执行修改

三、使用体验：AI 设计师能做什么？

有了这套系统，AI 不只是能「读」Figma——它能完整参与设计流程。

读懂设计： AI 可以获取任意节点的信息（尺寸、颜色、字体、位置）、获取当前选中元素、列出文件中的所有页面和组件。配合 get_document_info，AI 能「看到」整个文件的结构。

批量修改设计： 最实用的场景是批量替换。例如「把所有 #FF6B6B 的主色调改成 #E63946」——AI 会遍历所有填充色，找到匹配的节点，逐一替换。这对于换肤、 rebranding 等场景非常高效。

生成代码： AI 可以读取组件信息后，结合 prompt 中的最佳实践（prompts/index.ts），生成对应的 React/Vue/SwiftUI 组件代码。由于 AI 知道组件的精确尺寸、颜色、间距，生成的代码比截图识别更准确。

可访问性审计： 「找出所有对比度低于 WCAG AA 标准（4.5:1）的文本」——这是 AI 最擅长的场景，它能自动遍历所有文本节点，计算前景色与背景色的对比度，生成审计报告。

创建新元素： AI 可以创建矩形、文本、框架、椭圆等基础图形，并且支持通过 parentId 维持正确的层级结构。Creator 工具要求必须指定父节点 ID，防止元素「飘」到页面根部，这个设计很合理。

四、局限与挑战

尽管思路清晰，这套系统也有一些需要正视的问题。

延迟与可靠性： 整个链路涉及 MCP Server → WebSocket → Plugin → Figma API → Plugin → WebSocket → MCP Server，至少 3 跳 HTTP/WS 往返，加上 Figma API 的响应时间，端到端延迟通常在 500ms–3s 之间。对于单次操作影响不大，但如果 AI 需要反复试探（试颜色、试位置），累积延迟会很明显。

Plugin 安装门槛： 用户必须手动安装 Figma Plugin，并找到 channel ID 再告诉 AI，这一步对非技术用户有一定障碍。相比 Figma 官方的 MCP（配置更简洁），这是体验上的劣势。

命令路由的脆弱性： WebSocket Server 的队列机制虽然解决了并发问题，但 pluginClients 与 agentClients 的分类依赖 join 消息的类型标记。如果 Plugin 意外断开连接，队列中的命令会超时（120 秒），用户体验不佳。

测试覆盖： 项目有 tests/ 目录和 Jest 测试套件（jest.config.cjs），但 socket.ts 中的大量异步逻辑（队列、路由、超时）是测试难点，实际测试覆盖率未知。

五、开发者视角：代码质量分析

从代码架构来看，这是一个中等规模的 TypeScript 项目（90 个文件，核心逻辑约 3 个大文件）。

架构设计：模块化良好

代码组织清晰：tools/ 下每个文件对应一类工具，utils/ 下是通用能力（logger、schema-helpers、figma-helpers）。Server 入口（server.ts）只负责初始化，逻辑全部下沉到子模块，符合单一职责原则。

类型安全：Zod Schema 全覆盖

所有工具输入参数均用 Zod 定义 Schema，错误处理通过 try/catch 包裹返回 error.message，即使 Figma API 报错也不会导致 Server 崩溃。coerceJson 包装器处理 MCP 传来的 JSON 字符串参数，体现了防御性编程意识。

异步模式：Bun 原生性能

WebSocket Server 使用 Bun 的 ServerWebSocket 和 Bun.serve，而非第三方 WS 库，减少了依赖体积。channelQueues 的 Map 结构设计合理，支持多 channel 并发隔离。

测试覆盖： Jest 配置存在，但 tests/ 目录内容未知，CI 中有 test.yml 工作流。对于一个涉及网络通信、并发队列、文件系统操作的系统，测试缺失是潜在风险。

六、行业意义

Claude Talk to Figma MCP 代表了一个新兴方向：AI 驱动的前端工作流自动化。它不只是一个工具，更是「AI 作为设计参与者」这个理念的早期实践。

当前业界有几个类似的探索方向：

• Figma 官方 MCP（需 Dev Mode）
• VS Code Figma 插件（读取设计稿）
• Locof.ai 等 AI 设计转代码工具（截图/设计稿 → 代码）

本项目的独特价值在于双向操作——不仅能读，还能写，且不需要付费许可证。这让它特别适合个人开发者、独立设计师和小型团队。

从增长数据看：620+ Stars、115 Forks、6 个 Open Issues（说明有活跃的 Issue 反馈），在 MCP 相关项目中属于中等偏上热度。作者持续维护（CHANGELOG.md 有版本记录），社区贡献路径清晰（CONTRIBUTING.md）。

未来方向（从 README Roadmap 看）可能包括：

• 更智能的批量操作
• 设计变体（Variants）支持
• 设计 token 的自动同步
• 更多 AI 客户端的深度集成（不只是 Claude）

---

总结： Claude Talk to Figma MCP 是一款将 AI Agent 能力引入设计工作流的实用工具。它通过 MCP 协议 + WebSocket 中转 + Figma Plugin 的三层架构，让任何 AI 编程工具都能读写 Figma 设计稿。代码质量较高（TypeScript + Zod + Bun），架构清晰，适合对 AI + 设计交叉领域感兴趣的开发者和设计师探索使用。