1. 项目概述一个连接设计与开发的“翻译官”最近在折腾一个内部设计系统的协作流程发现一个挺普遍但又很磨人的问题设计师在Figma里更新了组件库开发同学得手动去Figma里看更新日志、截图、再对照着改代码一来一回沟通成本巨大还容易出错。直到我发现了这个叫sso-ss/figma-unified-mcp的项目它像是一个专门为Figma和开发工具之间架设的“高速翻译官”。简单来说figma-unified-mcp是一个实现了Model Context Protocol (MCP)标准的服务器。它的核心使命是把你在Figma文件里的设计元素——比如颜色、文本样式、组件变量——实时地、结构化地“翻译”成AI助手比如Claude Desktop、Cursor等能够理解和操作的数据。这意味着你不再需要手动在Figma和代码编辑器之间来回切换AI助手可以直接“看到”你的设计稿并根据你的指令帮你生成对应的代码、检查设计一致性甚至自动更新设计令牌。这个项目解决的不是一个简单的“导出”问题而是一个“双向同步与智能理解”的问题。它适合所有在团队协作中被“设计-开发”鸿沟困扰的开发者、设计师和工程效能工程师。无论你是想自动化生成设计系统的代码片段还是希望AI能基于最新的设计稿进行代码审查这个工具都能提供一个非常优雅的底层连接方案。接下来我就结合自己把它接入现有工作流的全过程拆解一下它的核心思路、实操细节以及那些容易踩坑的地方。2. 核心思路与架构拆解为什么是MCP在深入代码之前理解它为什么选择MCP协议至关重要。这决定了整个项目的设计哲学和扩展能力。2.1 MCP协议AI时代的“通用插座”你可以把MCP想象成AI助手世界里的“USB-C接口”。在过去每个AI工具Claude, Cursor, Windsurf想连接外部数据源如Figma, GitHub, 数据库都需要开发专属的、不兼容的插件。MCP的目标就是统一这个混乱的局面。它定义了一套标准的协议让AI助手客户端可以通过统一的方式去发现、调用不同数据源服务器提供的“工具”Tools和“资源”Resources。对于figma-unified-mcp而言它的角色就是一个MCP服务器。它利用Figma的官方API将Figma这个设计工具的能力“包装”成一系列标准的MCP工具和资源暴露给支持MCP的AI客户端。这样做有几个显著优势一次开发多处使用只要AI客户端支持MCP如Claude Desktop已原生支持就无需再为每个客户端单独开发Figma插件。能力标准化通过MCP定义的list_tools,call_tool,read_resource等标准接口AI客户端能以一致的方式与Figma交互降低了学习和集成成本。关注点分离服务器专心处理与Figma API的通信、数据转换和业务逻辑客户端专心处理与用户的交互和AI推理。架构清晰易于维护。2.2 项目架构与核心模块这个项目的代码结构清晰地反映了其MCP服务器的定位figma-unified-mcp/ ├── src/ │ ├── server/ # MCP服务器核心实现 │ ├── figma/ # Figma API客户端封装与数据处理 │ ├── tools/ # 具体的MCP“工具”实现 │ └── resources/ # 具体的MCP“资源”定义 ├── scripts/ # 构建与开发脚本 └── config/ # 配置文件示例核心工作流可以概括为启动服务器加载配置主要是Figma个人访问令牌和文件ID。注册能力向连接的AI客户端宣告“我这里有这些工具如get_file_components获取组件列表和资源如figma://colors颜色样式可用”。处理请求当AI客户端用户发出类似“请根据主按钮的样式生成React代码”的指令时客户端会调用服务器提供的相应工具。调用Figma API服务器在后台使用你的令牌向Figma API发起请求获取最新的设计数据。转换与响应将Figma返回的原始JSON数据过滤、清洗、转换成结构更清晰、对AI更友好的格式如只提取关键的name,fills等属性最后通过MCP协议返回给AI客户端。这个过程中最核心的价值在于数据转换层。Figma API返回的数据非常详尽但也包含大量UI渲染相关的元数据。figma-unified-mcp的核心工作之一就是做“减法”和“重塑”提取出设计系统中对开发有直接意义的语义化信息。3. 从零开始的配置与部署实战理论讲完了我们来看怎么把它用起来。整个过程可以分为获取凭证、本地配置、连接AI客户端三步。3.1 第一步获取Figma访问令牌Token这是所有操作的钥匙。没有它服务器无法访问你的Figma文件。登录Figma网站点击右上角头像进入「Settings」。在左侧菜单找到「Account」向下滚动到「Personal access tokens」部分。点击「Create new token」给它起个名字比如MCP-Server-Dev。权限Scopes选择需要的最小集通常file_read是必须的如果你需要它未来能写回注释等可以加上write_comment但出于安全初期只读即可。点击创建后立即复制生成的令牌字符串。它只显示一次丢失后需要重新生成。安全警告这个令牌等同于你的Figma账户密码。绝对不要将它提交到公开的Git仓库或分享给他人。我们接下来会把它放在本地配置文件中。3.2 第二步本地运行与配置服务器项目通常提供多种运行方式这里以最直接的本地Node.js运行和Docker运行为例。方案A使用Node.js直接运行适合开发调试# 1. 克隆项目 git clone https://github.com/sso-ss/figma-unified-mcp.git cd figma-unified-mcp # 2. 安装依赖 (确保你的Node.js版本 18) npm install # 3. 准备配置文件 cp config/default.example.json config/default.json # 编辑 config/default.json配置文件default.json是关键{ figma: { accessToken: 你的Figma个人访问令牌, fileIds: { 你的设计系统文件别名: Figma文件ID } }, server: { host: 127.0.0.1, port: 3000 } }如何获取fileIds打开你的Figma设计文件浏览器地址栏的URL格式是https://www.figma.com/file/FILE_KEY/file-name?node-id...。其中FILE_KEY就是文件ID。你可以为它设置一个易读的别名如design_system: abcDeFgHiJkL。host和port保持默认的127.0.0.1和3000即可这是服务器监听的地址。# 4. 启动服务器 npm start # 或用于开发监听文件变化 npm run dev如果看到类似MCP Server running on http://127.0.0.1:3000的日志说明服务器启动成功。方案B使用Docker运行适合生产或隔离环境# 1. 创建一个配置目录并生成配置文件 mkdir -p ~/figma-mcp-config cd ~/figma-mcp-config # 2. 创建配置文件内容同上方的 default.json nano config.json # 3. 使用Docker运行 docker run -d \ --name figma-mcp \ -p 3000:3000 \ -v $(pwd)/config.json:/app/config/default.json \ ghcr.io/sso-ss/figma-unified-mcp:latestDocker方式将配置通过卷-v挂载到容器内避免了将敏感令牌构建进镜像更安全方便。3.3 第三步连接AI客户端以Claude Desktop为例目前对MCP支持最友好的是Claude Desktop。打开Claude Desktop应用点击左上角「Claude」菜单选择「Settings」进入「Developer」设置页。找到「MCP Servers」配置部分。这里可以添加自定义的MCP服务器。点击「Add New Server」配置如下Name: 任意如Figma Design System。Command: 如果你用Node直接运行且npm start在后台这里其实Claude会自己处理。更通用的方式是使用npx命令。但更推荐下面这种配置。实际上对于已启动的HTTP服务器MCP也支持直接连接一个已经启动的HTTP/SSE服务器。在配置中你可以使用url: http://127.0.0.1:3000/sse的方式。不过具体需要查看figma-unified-mcp的文档看它暴露的是Stdio模式还是HTTP/SSE端点。对于本项目更常见的MCP连接方式是通过标准输入输出stdio。你可以在Claude的配置中使用一个启动脚本。创建一个Shell脚本如start_figma_mcp.sh:#!/bin/bash cd /path/to/your/figma-unified-mcp npm start然后在Claude的MCP配置中Command填写这个脚本的绝对路径。保存配置并重启Claude Desktop。重启后在Claude的对话界面你应该能看到一个小的插件图标被激活或者你可以直接问Claude“你现在能访问Figma设计系统吗” 如果配置成功Claude会回复它已连接上Figma服务器并可以列出可用的工具。4. 核心功能深度解析与使用场景连接成功只是开始理解服务器提供了哪些“工具”和“资源”才能发挥最大威力。根据代码和MCP的特性我们可以推断并实践其核心功能。4.1 核心工具Tools详解工具是AI可以主动调用的函数。在Claude中你可以通过“你能对Figma做什么”来触发它列出所有工具。get_file_info(获取文件信息)作用获取指定Figma文件的基本元数据如文件名、最后修改时间、包含的页面等。AI调用场景“我们目前在用哪个Figma文件”、“设计系统文件最近有更新吗”背后逻辑服务器调用Figma API的GET /v1/files/:key端点返回精简后的文件信息帮助AI建立上下文。get_file_components(获取组件列表)作用提取文件中所有发布的组件Component和组件集Component Set。AI调用场景“把我们的按钮组件都列出来”、“设计系统里有多少个输入框组件”数据转换要点这是价值所在。原始API返回的组件信息包含大量节点数据。此工具会过滤只保留关键信息组件名称、描述如果有、关键属性如变体属性Variant并可能生成一个唯一的引用ID。这极大减少了AI处理的噪音。get_file_styles(获取样式列表)作用获取文件中定义的颜色、文本、效果等样式。AI调用场景“我们的主色调和辅助色是什么”、“标题H1的字体样式是怎样的”实操心得样式是设计令牌Design Tokens的直接来源。这个工具的输出是自动化生成CSS变量或Theme对象最直接的依据。AI可以基于此生成:root { --primary: #007bff; }或const colors { primary: #007bff }。get_component_details(获取组件详情)作用根据组件ID获取该组件的详细构成信息包括其图层结构、尺寸、填充色、边框、文本内容等。AI调用场景“把Primary Button的尺寸、圆角、内边距和文字内容告诉我”、“这个卡片的阴影效果参数是多少”深度解析这是最复杂的工具之一。它可能递归地获取组件实例的节点树并将Figma的绝对坐标、混合模式等设计属性转换为对开发更友好的相对值如间距、字体层级。例如它可能会计算出按钮内部文字距离边框的padding而不是文字的绝对x, y坐标。4.2 核心资源Resources详解资源是AI可以读取的静态数据URI。你可以理解为一些预定义的数据查询端点。figma://colors(颜色资源)作用提供一个持续更新的颜色样式列表流。使用方式AI客户端可以“订阅”这个资源。当Figma中的颜色样式发生变化服务器可以通过SSEServer-Sent Events主动推送更新给AI如果协议支持。这为实现“设计变更实时同步到开发环境”提供了可能。场景想象设计师在Figma里调整了品牌色几分钟后AI助手在代码评审中就能提示“这个#oldColor已被新的#newBrandColor取代建议更新。”figma://text_styles(文本样式资源)作用与颜色资源类似但专注于文本样式字体、字号、行高、字重等。开发对接这是确保产品视觉一致性的关键。AI可以读取这些资源来检查代码中的font-family、font-size是否与设计规范匹配。4.3 高级使用场景串联单独的工具已经有用但将它们串联起来才能体现AI的智能。场景一自动化生成组件代码你可以对AI说“请根据Figma设计系统中名为Button/Primary的组件生成一个React函数组件要求包含TypeScript类型定义并使用Tailwind CSS实现样式。” AI的工作流将是调用get_file_components找到Button/Primary及其ID。调用get_component_details获取该按钮的尺寸、颜色、文字、圆角等细节。结合get_file_styles将颜色值映射为对应的CSS变量或Tailwind色彩类。综合以上信息组装出符合要求的React代码。场景二设计走查与代码审查在代码评审时AI可以主动工作“请检查当前React组件中所有按钮的样式是否与Figma设计系统v2.1文件中的规范一致。” AI会解析当前代码文件提取所有按钮元素的样式属性。从Figma服务器获取最新的按钮组件样式规范。进行比对并生成报告“发现3处不一致提交按钮的背景色应为blue-600当前为blue-500取消按钮的边框宽度应为2px当前缺失...”场景三设计令牌同步这是更工程化的场景。可以建立一个自动化脚本或CI/CD流程定期通过figma-unified-mcp服务器或直接调用其封装逻辑获取figma://colors和figma://text_styles资源并将其转换为JSON文件然后通过脚本自动生成对应平台的代码如iOS的UIColor扩展、Android的colors.xml、Web的tokens.css。figma-unified-mcp作为MCP服务器其数据转换逻辑可以被复用即使不在AI对话场景中。5. 实操中的常见问题、排查与优化在实际集成过程中你肯定会遇到各种问题。下面是我踩过坑后总结的排查清单和优化建议。5.1 连接与权限问题排查表问题现象可能原因排查步骤与解决方案Claude提示“无法连接MCP服务器”或“未找到工具”1. 服务器未启动2. Claude配置命令错误3. 网络/端口冲突1.检查进程在终端运行lsof -i:3000或netstat -ano | findstr :3000看端口是否被占用进程是否运行。2.检查日志查看服务器启动终端的日志是否有错误输出如Token无效。3.简化测试先用curl http://127.0.0.1:3000/health(如果服务器暴露了健康检查端点) 或直接运行配置的Command脚本看能否独立运行。服务器日志显示401 UnauthorizedFigma个人访问令牌无效或权限不足1.确认令牌在Figma设置中检查令牌是否已启用是否包含file_read权限。2.重置令牌最直接的方法是去Figma设置里撤销旧令牌生成一个新令牌更新配置文件。3.检查文件权限确保该令牌所属的账户有权限访问config.json中配置的fileIds。AI能连接但获取数据为空或报错1. Figma文件ID错误2. 文件内无对应内容如无发布组件3. API速率限制1.核对File ID再次从浏览器地址栏确认文件KEY并确保在Figma中所需的组件和样式已经通过‘发布’按钮发布到团队库。MCP服务器读取的是已发布的库资源而非未发布的本地组件。2.查看原始API用令牌直接调用Figma API测试curl -H X-Figma-Token: YOUR_TOKEN https://api.figma.com/v1/files/FILE_KEY看能否返回数据。3.处理限流Figma API有调用频率限制。如果请求频繁失败需要在服务器代码中增加重试机制和延迟。figma-unified-mcp项目可能已经内置了简单的缓存但对于高频使用你可能需要自己增强。5.2 性能优化与高级配置启用数据缓存频繁调用Figma API会触发限流且速度慢。理想的figma-unified-mcp实现应该包含缓存层。检查项目配置看是否有缓存设置。例如可以配置一个内存或Redis缓存将文件信息、组件列表等TTL生存时间较长的数据缓存起来如5-10分钟而不是每次AI请求都访问Figma API。处理大型设计文件如果设计系统文件非常庞大一次性获取所有组件或样式可能超时或返回数据过大。需要优化工具的实现支持分页Pagination或增量获取。例如get_file_components工具可以接受page和limit参数。自定义工具扩展MCP服务器的强大之处在于可扩展性。如果你有特殊需求比如想获取特定页面的所有画板或者计算两个组件的间距规则你可以仿照src/tools/下的模式创建自己的工具。例如创建一个calculate_spacing_tokens工具专门分析设计稿中的间距规律并输出成8px倍数的尺度。多文件与别名管理在config.json的fileIds里你可以配置多个文件。确保你的工具实现能根据传入的参数如fileAlias来切换不同的文件上下文。这样AI就可以在不同项目的设计文件之间切换。5.3 安全最佳实践令牌隔离永远不要在客户端代码或公开配置中硬编码Figma令牌。在服务器端配置中使用环境变量或安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault来注入令牌。# 启动时使用环境变量 FIGMA_ACCESS_TOKENyour_token_here npm start然后在代码中通过process.env.FIGMA_ACCESS_TOKEN读取。网络隔离将figma-unified-mcp服务器部署在内网或仅限本地访问127.0.0.1。如果Claude Desktop在本地那么服务器运行在本地是最安全的。避免将服务器暴露在公网。最小权限原则为MCP服务器创建的Figma令牌只授予它完成工作所必需的最小权限如file_read。不要授予write_*权限除非你明确需要AI执行修改操作。6. 与其他方案对比及未来展望在遇到figma-unified-mcp之前团队可能尝试过其他集成方式手动导出/同步设计师导出JSON或使用style-dictionary等工具手动触发。问题在于非实时、易遗漏、流程断裂。Figma插件自定义脚本编写Figma插件监听变更调用webhook通知后端服务。这种方式更直接但开发维护成本高且与AI生态结合较弱。直接调用Figma API在CI/CD中写脚本直接拉取数据。这解决了自动化问题但缺少一个“智能中间层”来理解设计数据的语义并将其适配到AI的交互模式。figma-unified-mcp的价值在于它站在了MCP这个新兴标准的肩膀上专注于做好一件事成为Figma数据通往AI世界的一座标准化、结构化的桥梁。它可能不是功能最全的但它的设计理念决定了其更好的兼容性和进化潜力。从实际体验来看这个项目目前可能还处于比较早期的阶段工具的丰富度、错误处理的健壮性、性能优化等方面都有很大的打磨空间。但这正是开源项目的魅力所在。你可以基于它深度定制符合自己团队工作流的工具比如增加一个generate_icon_sprite工具自动将Figma中的图标组件打包成SVG雪碧图并生成React组件或者创建一个audit_design_tokens工具对比代码中的样式值与Figma规范生成差异报告。我个人认为随着MCP协议的普及和AI编程助手的深度集成这类“专用数据源MCP服务器”会像雨后春笋一样出现。figma-unified-mcp为设计-开发工作流自动化提供了一个非常清晰的范本。它的终极目标是让设计师和开发者共享同一套“设计事实来源”并通过AI这个“智能代理”无缝地弥合两个领域之间的鸿沟把我们从繁琐的同步和核对工作中彻底解放出来。