1. 项目概述一个连接设计工具与AI的“翻译官”最近在折腾一个挺有意思的项目叫sso-ss/figma-unified-mcp。乍一看这个标题熟悉开源社区的朋友可能立刻会心一笑这又是一个典型的“个人或小团队为解决特定痛点而生的工具”。简单来说它的核心使命是让 AI 助手比如 Claude、Cursor 等能够“看懂”并“操作”你的 Figma 设计文件。你可以把它想象成一个架设在 Figma 和 AI 之间的“翻译官”或“桥梁”。为什么需要这样一个桥梁在当前的 AI 浪潮下设计师和开发者都希望能用自然语言来驱动设计工具比如对 AI 说“帮我把首页的按钮颜色改成品牌蓝色并导出为 2x 的 PNG”然后 AI 就能自动完成。但现实是Figma 的 API 功能强大却复杂AI 模型本身并不直接理解如何调用这些 API。这就需要一套标准化的“协议”来告诉 AI“如果你想操作 Figma你应该这样和我说话我会帮你把话翻译成 Figma 能听懂的命令。” 这正是Model Context Protocol (MCP)要解决的问题而figma-unified-mcp就是针对 Figma 这个具体工具实现的 MCP 服务器。这个项目特别适合三类人一是希望提升设计工作流自动化程度的设计师或前端工程师二是热衷于探索 AI 与工具链结合的开发者三是任何对“用自然语言编程”这一前沿交互模式感兴趣的技术爱好者。通过它你可以将 Figma 的设计资源、图层信息、甚至操作能力无缝集成到你的 AI 工作流中让创意和执行的边界变得更加模糊。2. 核心架构与 MCP 协议解析2.1 什么是 MCP以及它为何是关键要理解figma-unified-mcp必须先搞懂 MCP。Model Context Protocol 是由 Anthropic 公司提出的一种开放协议旨在为 AI 模型大语言模型提供一个标准化的方式来发现、调用外部工具和资源。你可以把它类比成 AI 世界的“USB 标准”或“驱动模型”。在没有 MCP 之前每个 AI 应用如果想连接某个工具比如 Figma、数据库、搜索引擎都需要自己编写一套复杂的适配逻辑而且这些逻辑无法在不同 AI 模型间复用。MCP 的出现定义了一套统一的“插拔”接口服务器Server比如我们的figma-unified-mcp它封装了对 Figma API 的所有操作并按照 MCP 规定的格式暴露出来。客户端Client比如 Claude Desktop、Cursor 等 AI 应用它们内置了 MCP 客户端知道如何按照协议去发现和调用服务器提供的工具。协议Protocol基于 JSON-RPC 的通信标准规定了客户端和服务器之间如何打招呼初始化、服务器能提供什么工具资源列表、以及如何调用这些工具执行请求。为什么选择 MCP 而不是其他方式标准化与生态MCP 正在成为 AI 工具集成的事实标准支持它的客户端越来越多意味着你为 Figma 写一次 MCP 服务器就能在 Claude、Cursor 等多个地方使用。安全与可控MCP 连接通常是本地的或受严格控制的服务器需要明确的权限如 Figma 个人访问令牌才能操作避免了将敏感设计数据直接发送给不可控的第三方 AI 服务。能力丰富MCP 不仅支持执行命令Tools还支持提供只读数据Resources比如可以把 Figma 文件的结构以特定格式如 JSON提供给 AI 作为上下文让 AI 的回复更精准。2.2figma-unified-mcp的整体设计思路这个项目的目标很明确实现一个功能完备、稳定可靠的 Figma MCP 服务器。它的“Unified”统一一词暗示了其设计志向——可能希望覆盖 Figma API 的主要功能提供一个统一的接口层而不是零散的工具集合。从技术架构推测它很可能包含以下核心模块MCP 协议适配层负责处理与 MCP 客户端的通信解析 JSON-RPC 请求并按照 MCP 规范格式返回结果。这是项目的“外壳”。Figma API 客户端层封装了对 Figma REST API 的所有调用。这里需要处理认证使用 Personal Access Token、请求速率限制、错误重试等网络交互细节。业务逻辑与工具层这是核心价值所在。它将 Figma 的复杂操作抽象成一个个简单的 MCP “工具”。例如list_files列出用户可访问的 Figma 团队和文件。get_file_nodes获取指定文件中特定节点的详细信息如位置、尺寸、样式。update_fill_color修改某个图层的填充颜色。export_node导出某个节点为图片。create_frame创建一个新的画板Frame。数据转换层Figma API 返回的数据结构非常详细且嵌套很深而 AI 处理和理解扁平、简洁的数据结构更高效。这一层负责将 Figma 的原生响应转换成对 AI 更友好的格式例如将复杂的 Paint 对象简化为#HEX颜色字符串。项目的技术栈通常会是 Node.jsTypeScript因为这是 Figma 插件开发的官方语言生态完善且能很好地处理异步 IO。它会重度依赖figma/rest-api-spec等官方或社区类型定义库来保证 API 调用的类型安全。3. 核心功能拆解与实操要点3.1 身份认证与安全配置任何与 Figma API 交互的工具安全都是第一位。figma-unified-mcp的核心是 Figma 的个人访问令牌。1. 获取 Figma Personal Access Token (PAT)登录 Figma 官网进入个人设置Settings。在 “Account” 标签页下找到 “Personal access tokens” 部分。点击 “Create new token”为其命名例如MCP-Server并谨慎选择权限范围。对于大多数只读和基础修改操作通常需要勾选file_read和file_write。原则是按需分配最小权限。不要一股脑儿全选。创建后立即复制并妥善保存这个令牌字符串。它只会显示一次拥有它就意味着拥有了对应权限下对你的 Figma 账户的操作能力。2. 在 MCP 客户端配置服务器以 Claude Desktop 为例你需要编辑其配置文件通常位于~/Library/Application Support/Claude/claude_desktop_config.json或 Windows 的%APPDATA%对应目录。{ mcpServers: { figma: { command: npx, args: [ -y, sso-ss/figma-unified-mcp ], env: { FIGMA_ACCESS_TOKEN: 你的_PAT_令牌 } } } }关键提示永远不要将你的 PAT 直接硬编码在代码或公开的配置文件中。使用环境变量如FIGMA_ACCESS_TOKEN是标准做法。在团队协作中可以考虑使用本地的.env文件并加入.gitignore或秘密管理工具。3.2 核心工具详解与使用示例配置成功后启动你的 MCP 客户端如 Claude DesktopAI 助手就能“发现” Figma 工具了。以下是几个核心工具的使用逻辑工具一浏览与查询文件结构这是最常用的功能。你可以让 AI “列出我的 Figma 文件” 或 “查找‘登录页’文件中所有叫‘按钮’的组件”。背后原理AI 会调用list_files工具该工具向https://api.figma.com/v1/me/files发送请求返回文件列表。当查询具体文件节点时调用get_file_nodes使用 Figma 的GET /v1/files/:key/nodes?ids...接口获取节点的绝对几何信息、样式、组件信息等。实操指令示例对 AI 说“请帮我找到文件‘Website V2’中页面‘Homepage’里所有的‘Button’组件并告诉我它们的颜色和尺寸。”AI 操作流程调用list_files找到名为 “Website V2” 的文件 Key。调用get_file_nodes传入文件 Key 和节点查询参数可能需要先遍历页面结构找到‘Homepage’的画板ID。接收并解析 Figma 返回的复杂 JSON提取出每个 Button 节点的fills填充属性中的颜色值以及absoluteBoundingBox中的宽高信息。将提取的信息用自然语言组织后回复给你。工具二修改设计属性这是体现自动化的核心。例如“将首页主标题的颜色改为 #1A73E8”。背后原理AI 调用update_fill_color工具。该工具需要至少三个参数file_key、node_id和color。它内部会将#1A73E8转换为 Figma API 接受的rgba格式对象如{r: 0.102, g: 0.451, b: 0.909, a: 1}然后向PUT /v1/files/:key/nodes端点发送请求执行更新操作。注意事项节点 ID 的获取修改前通常需要先通过查询工具获取目标节点的唯一 ID。Figma 的节点 ID 是字符串在文件内唯一。样式继承与覆盖如果目标节点是某个主组件的实例直接修改其属性可能会创建样式覆盖。AI 工具的逻辑需要明确是修改此实例还是去修改其主组件。目前的工具大多针对实例进行直接修改。网络延迟与并发Figma API 有速率限制。工具内部需要实现良好的队列或延迟处理避免短时间内发起大量请求导致被限流。工具三导出资产“将导航栏的 Logo 导出为 2x 的 PNG 文件保存到我的桌面。”背后原理调用export_node工具参数包括file_key、node_id、format(png, jpg, svg等)、scale(1, 2, 3等)。工具调用 Figma 的GET /v1/images/:filekey接口生成图片链接然后由服务器或客户端下载该图片到指定路径。实操心得导出操作是异步的。Figma API 首先返回一个包含图片 URL 的响应但这个 URL 可能不会立即生效需要几秒处理时间。一个健壮的export_node工具需要实现轮询或等待机制确保能成功获取到最终的图片数据。此外处理下载路径和文件命名也是提升体验的关键。4. 开发与集成深度实操4.1 本地运行与调试指南如果你想深入理解或贡献代码需要搭建本地开发环境。步骤 1克隆与准备git clone https://github.com/sso-ss/figma-unified-mcp.git cd figma-unified-mcp npm install # 或 pnpm install / yarn install确保你的 Node.js 版本符合项目要求通常在package.json的engines字段中注明。步骤 2环境变量配置在项目根目录创建.env文件FIGMA_ACCESS_TOKEN你的_PAT_令牌 # 可能还有其他配置如日志级别、代理设置等 LOG_LEVELdebug注意将.env加入.gitignore避免意外提交密钥。步骤 3以开发模式运行 MCP 服务器MCP 服务器通常通过标准输入输出stdio与客户端通信。你可以使用项目提供的开发脚本或者直接运行npm run dev但这通常只是启动服务器。为了调试你需要一个 MCP 客户端来连接它。一个高效的方法是使用MCP Inspector工具例如modelcontextprotocol/inspector它可以作为一个调试客户端可视化地查看服务器提供的所有工具和资源并手动触发调用观察请求和响应。npx modelcontextprotocol/inspector npm run dev这样你就能在一个本地网页界面中像使用 Postman 测试 API 一样测试你的 Figma MCP 工具极大方便了开发和排错。步骤 4连接至真实 AI 客户端测试在本地开发时你可以修改 Claude Desktop 的配置让其指向本地服务器进程而不是从 npm 全局安装。{ mcpServers: { figma-local: { command: node, args: [/你的/本地/项目/路径/dist/index.js], env: { FIGMA_ACCESS_TOKEN: 你的_PAT_令牌 } } } }重启 Claude Desktop 后你就可以在对话中直接使用本地开发版本的 Figma 工具了。4.2 扩展自定义工具假设项目现有的工具不满足你的需求比如你想增加一个“批量重命名图层”的功能。1. 在工具定义文件中添加新工具在src/tools/目录下假设项目结构如此新建或编辑一个文件例如layer-management.ts。你需要使用 MCP SDK如modelcontextprotocol/sdk来定义工具。import { Tool } from modelcontextprotocol/sdk/server.js; import { z } from zod; // 通常用于参数验证 export const renameLayersTool: Tool { name: rename_figma_layers, description: 批量重命名Figma文件中的指定图层, inputSchema: { type: object, properties: { fileKey: { type: string, description: Figma文件Key }, nodeIds: { type: array, items: { type: string }, description: 需要重命名的图层节点ID数组 }, newNames: { type: array, items: { type: string }, description: 对应的新名称数组顺序需与nodeIds一致 } }, required: [fileKey, nodeIds, newNames] }, // handler函数是工具的核心逻辑 handler: async (args: any, extra: any) { const { fileKey, nodeIds, newNames } args; // 1. 参数校验 if (nodeIds.length ! newNames.length) { throw new Error(节点ID数组与新名称数组长度必须一致); } // 2. 调用Figma API需要实现一个Figma客户端 const results []; for (let i 0; i nodeIds.length; i) { try { // 假设有一个封装好的figmaClient await figmaClient.updateNodeName(fileKey, nodeIds[i], newNames[i]); results.push({ nodeId: nodeIds[i], success: true, newName: newNames[i] }); } catch (error) { results.push({ nodeId: nodeIds[i], success: false, error: (error as Error).message }); } } // 3. 返回MCP格式的结果 return { content: [{ type: text, text: 批量重命名完成。成功${results.filter(r r.success).length}失败${results.filter(r !r.success).length}。详情${JSON.stringify(results)} }] }; } };2. 将新工具注册到服务器在主服务器文件如src/server.ts中导入并注册这个新工具。import { renameLayersTool } from ./tools/layer-management.js; // ... 在服务器初始化部分 server.setRequestHandler(ToolsListRequest, async () { return { tools: [ // ... 其他已存在的工具 renameLayersTool, // 添加新工具 ], }; });3. 实现底层的 Figma 客户端方法你需要在figmaClient中实现updateNodeName方法。这需要研究 Figma API 文档找到更新节点属性的正确端点可能是PUT /v1/files/:key/nodes并操作name属性。4. 测试与迭代使用前面提到的 MCP Inspector 或连接 Claude Desktop 测试你的新工具。注意处理 Figma API 的速率限制在批量操作中可能需要加入延迟。5. 常见问题、排查技巧与优化实践5.1 连接与认证问题问题1AI 客户端提示“无法连接到 Figma MCP 服务器”或“未找到 Figma 工具”。排查步骤检查配置语法仔细核对 MCP 客户端配置文件如claude_desktop_config.json的 JSON 格式确保没有缺少逗号或括号。验证命令路径如果使用本地路径确保command和args指向正确的可执行文件。对于 Node.js 项目通常command是nodeargs是入口文件路径。查看客户端日志Claude Desktop 通常有日志输出位置在设置中或特定目录。查看日志中关于 MCP 服务器启动的错误信息。手动运行服务器在终端中直接运行配置中的命令看服务器是否能独立启动并输出就绪信息而不是立即报错退出。问题2工具调用失败提示“未授权”或“Invalid token”。排查步骤确认 PAT 有效性前往 Figma 设置页面检查你的 PAT 是否已被意外撤销或过期。检查权限范围确认当前操作如写入所需的权限file_write已包含在 PAT 的权限集中。环境变量注入确保在 MCP 客户端配置中env字段正确设置了FIGMA_ACCESS_TOKEN并且其值无误。可以尝试在服务器启动脚本中打印环境变量值在开发模式下进行确认。网络代理问题如果你在公司网络或使用代理可能需要为服务器进程配置 HTTP 代理否则可能无法访问api.figma.com。5.2 工具调用与逻辑错误问题3AI 可以列出文件但获取节点详情或执行修改时失败。排查步骤验证节点 ID确保传递给工具的node_id是正确且完整的。Figma 的节点 ID 在文件加载后可能通过 API 获取不同版本的文件节点 ID 可能不同。检查文件 Key确认使用的file_key是文件 URL 中的那串字符且你有该文件的访问权限对于团队文件PAT 所属账户必须有相应权限。解读错误信息仔细阅读工具返回的错误信息。Figma API 的错误响应通常比较清晰例如404表示节点未找到403表示无权限429表示请求过多。使用 MCP Inspector 调试这是最有效的方法。手动在 Inspector 中构造相同的请求参数观察原始请求和响应能快速定位是参数问题还是服务器逻辑问题。问题4批量操作如导出多个图层速度慢或部分失败。优化与实践实现请求队列与退避在服务器代码中不要用Promise.all无脑并发所有 Figma API 调用。Figma API 有严格的速率限制例如每分钟数十次。实现一个简单的队列控制并发数如每秒 2-3 个请求并在收到429状态码时自动延迟重试指数退避。利用批量 API查阅 Figma API 文档看是否有批量操作的端点。例如获取多个节点详情可以使用一个请求传递多个node_ids。导出图片也可以一次请求多个节点。异步处理与进度反馈对于非常耗时的操作可以考虑实现 MCP 的“长任务”或“进度通知”机制如果协议支持或者至少返回一个任务 ID让用户可以通过其他工具查询状态。5.3 性能与体验优化1. 缓存策略频繁查询文件结构如列出所有页面、组件会对 Figma API 造成不必要的压力也影响响应速度。可以在服务器层面实现一个轻量级的缓存。缓存什么文件元数据列表、文件结构树node hierarchy。这些数据在短时间内变化不频繁。如何实现使用内存缓存如 Node.js 的Map或轻量级持久化缓存如node-cache库。为每个file_key设置一个缓存键并设定合理的 TTL例如 30 秒或 1 分钟。缓存失效当执行任何写入操作如修改颜色、重命名后必须使对应文件的缓存失效以确保下次读取到最新数据。2. 错误处理与用户提示AI 助手展示的错误信息应该对用户友好。封装错误在工具handler中捕获所有底层错误网络错误、API 错误、逻辑错误并将其转换为结构化的、包含可操作建议的错误信息返回给 MCP 客户端。示例不要直接返回“Figma API Error: 404 Not Found”而是返回“未能找到指定的图层。请确认1. 文件 Key 是否正确2. 该图层是否已被删除3. 您可以尝试先使用‘列出文件节点’工具确认图层 ID。”3. 指令编写的技巧为了让 AI 更准确地使用工具你在对话时给出的指令需要更清晰。提供上下文在要求修改前先让 AI 查询并确认目标。例如“请先找到文件‘XXX’中名为‘提交按钮’的组件确认其当前颜色然后将其改为 #FF6B6B。”明确参数对于导出操作明确格式、尺寸和缩放倍数。“将Logo导出为SVG格式2倍缩放。”分步进行复杂的操作可以拆分成多个指令降低 AI 单次调用的复杂度也便于你跟踪每一步的结果。这个项目代表了 AI 与专业工具深度集成的一个生动范例。它不仅仅是节省几次点击更是将设计资产的查询、修改、导出能力变成了可编程、可组合的“乐高积木”为更高级别的设计系统管理、设计稿与代码同步、自动化测试等场景打开了大门。我在实际集成和使用中发现最大的挑战往往不在于技术实现而在于设计一套既能让 AI 理解、又能覆盖常见用户意图的工具抽象层。figma-unified-mcp这样的项目正是在探索这个抽象层的最佳实践。随着 MCP 生态的成熟未来我们或许真的可以只用自然语言就能流畅地驱动整个数字产品创造流程。