1. 项目概述Figma UI 与 MCP 的桥梁最近在折腾一些自动化设计流程发现一个挺有意思的项目TranHoaiHung/figma-ui-mcp。简单来说这是一个Model Context Protocol (MCP) 服务器专门用来连接Figma和你的AI 助手比如 Claude Desktop、Cursor 等。它的核心价值在于让你能用自然语言直接操作 Figma 文件比如“把那个按钮的颜色改成蓝色”、“把这两个图层对齐一下”AI 助手就能理解并帮你执行。这听起来可能有点抽象我打个比方。以前你要改设计稿得自己打开 Figma找到图层手动调整属性一套操作下来虽然不复杂但打断思路。现在有了这个 MCP 服务器就像给你的 AI 配了一个懂 Figma 的“手”和“眼”。你只需要告诉 AI 你的意图它就能通过这个服务器去“看”你的设计稿获取节点信息然后“动手”修改更新节点属性。这对于快速原型迭代、批量修改设计规范、甚至是基于文本描述生成简单 UI 组件都提供了全新的可能性。这个项目适合谁呢首先是设计师和前端工程师尤其是那些需要频繁在设计和代码之间切换或者管理大型设计系统的人。其次是AI 应用开发者如果你想构建一个能理解并操作 UI 设计的智能体这个项目提供了一个绝佳的起点。最后任何对设计流程自动化和人机交互新范式感兴趣的技术爱好者都值得花时间研究一下。它不仅仅是省了几次点击更是打通了自然语言与图形界面创作工具之间的壁垒。2. 核心架构与 MCP 协议解析要理解figma-ui-mcp怎么工作得先搞明白 MCP 是什么。Model Context Protocol 是由 Anthropic 提出的一种开放协议旨在为 AI 模型大语言模型提供一种标准化的方式来访问外部工具、数据和功能。你可以把它想象成 AI 模型的“插件系统”或“驱动库”。一个 MCP 服务器就是一个提供了特定能力比如操作 Figma、查询数据库、控制智能家居的后端服务它通过标准的 HTTP 或 stdio 与 AI 客户端通信。2.1 MCP 的核心通信模型MCP 定义了几种核心的“资源”Resources和“工具”Tools资源代表 AI 可以读取的信息源。比如一个“资源”可以是一个 Figma 文件或者文件中的某个页面。AI 通过“读”资源来获取上下文。工具代表 AI 可以执行的操作。比如“更改图层颜色”、“重命名画板”就是工具。AI 通过“调用”工具来改变外部状态。figma-ui-mcp项目就是实现了针对 Figma 的资源和工具。它内部封装了 Figma 的 REST API并将这些 API 的能力“翻译”成了 MCP 协议能理解的格式。整个数据流是这样的你在 AI 客户端如 Claude Desktop里输入“获取当前文件的主页面列表”AI 模型理解你的意图后会通过 MCP 协议向配置好的figma-ui-mcp服务器发送一个请求。服务器收到后会使用你预先配置的 Figma 个人访问令牌去调用真正的 Figma API拿到数据后再通过 MCP 协议返回给 AIAI 最后以友好的格式呈现给你。2.2 项目结构与技术栈选择浏览项目代码你会发现它通常包含以下核心部分MCP 服务器实现使用 Node.js 和modelcontextprotocol/sdk这个官方 SDK 来构建。这是最合理的选择因为 SDK 处理了协议通信的底层细节开发者只需关注业务逻辑即 Figma API 的调用。Figma API 客户端可能会使用官方的figma-api库或直接使用axios等 HTTP 客户端封装请求。这里的关键是处理好认证Personal Access Token和 API 速率限制。资源与工具定义这是项目的核心。需要精确定义哪些 Figma 对象如文件、页面、节点作为“资源”暴露以及提供哪些“工具”如list_pages,get_node,update_fills等。设计时需要考虑工具的原子性和组合性既要足够细粒度以满足灵活需求又不能太琐碎导致使用复杂。配置管理如何让用户方便地配置 Figma 令牌和目标文件 ID。常见做法是通过环境变量或配置文件。注意在实现自己的 MCP 服务器或使用此类项目时务必妥善保管你的 Figma Personal Access Token。这个令牌拥有调用 API 的所有权限一旦泄露他人可以任意访问和修改你的设计文件。最佳实践是仅将令牌存储在本地环境变量中绝不提交到代码仓库。选择 Node.js 生态是因为其异步 I/O 特性非常适合这种网络代理型服务并且 MCP 官方 SDK 首先提供了 JS/TS 版本社区支持最好。整个架构是典型的轻量级中间层职责清晰协议转换 API 代理。3. 环境配置与服务器部署实操理论说得再多不如动手跑起来。下面我以在本地开发环境运行figma-ui-mcp为例拆解完整的配置和启动过程。假设你已经有了 Node.js (18) 和 npm 环境。3.1 获取 Figma 个人访问令牌这是连接 Figma API 的钥匙。登录你的 Figma 账号点击右上角头像进入“Settings”。在左侧菜单中找到“Account”向下滚动到“Personal access tokens”部分。点击“Create new token”给它起个名字比如 “MCP-Server-Local”。创建成功后立即复制生成的令牌字符串。这个页面只会显示一次关闭后就无法再次查看。如果丢失需要重新生成。3.2 克隆与安装项目# 克隆项目代码到本地 git clone https://github.com/TranHoaiHung/figma-ui-mcp.git cd figma-ui-mcp # 安装项目依赖 npm install如果项目提供了package.json这一步通常很顺利。有时你可能需要检查一下是否有 TypeScript 编译步骤查看scripts里是否有build命令。3.3 配置连接参数项目通常需要知道两件事你的令牌Token和你要操作的文件File ID。配置方式因项目设计而异最常见的是通过环境变量。方式一使用.env文件推荐在项目根目录创建.env文件FIGMA_PERSONAL_ACCESS_TOKEN你的令牌字符串 FIGMA_FILE_ID你的Figma文件ID如何获取 File ID打开你的 Figma 文件浏览器地址栏的 URL 格式类似https://www.figma.com/file/FILE_ID/文件名。其中FILE_ID就是你要填的。方式二直接传入启动命令FIGMA_PERSONAL_ACCESS_TOKENtoken FIGMA_FILE_IDfile_id node build/index.js3.4 启动 MCP 服务器根据项目的实现启动命令可能略有不同。如果项目是 TypeScript 编写可能需要先编译npm run build然后运行编译后的 JS 文件node dist/index.js或者如果项目使用了ts-node可能直接npm start成功的启动日志会显示服务器正在监听某个 stdio 或端口等待 MCP 客户端的连接。3.5 配置 AI 客户端以 Claude Desktop 为例这是让 AI 助手知道“桥”在哪里的关键一步。打开 Claude Desktop 应用。进入设置Settings找到 “Developer” 或 “MCP” 设置部分。你需要编辑 Claude 的配置文件。在 macOS 上通常位于~/Library/Application Support/Claude/claude_desktop_config.json。在 Windows 上位于%APPDATA%\Claude\claude_desktop_config.json。在配置文件中添加你的 MCP 服务器配置。配置结构如下{ mcpServers: { figma: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/figma-ui-mcp/project/dist/index.js ], env: { FIGMA_PERSONAL_ACCESS_TOKEN: 你的令牌, FIGMA_FILE_ID: 你的文件ID } } } }关键点command必须是node。args必须是你的服务器入口文件的绝对路径。使用相对路径很可能导致 Claude 找不到。env这里的环境变量会传递给启动的服务器进程。你也可以选择将敏感信息放在这里而不是项目本地的.env文件这样更便于管理多个配置。保存配置文件并完全重启 Claude Desktop 应用。重启后在聊天界面你应该能看到 Claude 的回复中提及它已连接了新的工具比如“Figma UI tools”。你可以直接问它“你现在有哪些可用的工具”来验证。4. 核心工具使用详解与场景演练服务器跑通客户端连上接下来就是看看这把“瑞士军刀”到底有哪些功能片。我们结合几个实际场景来深入理解每个工具的使用方法和背后的原理。4.1 场景一快速审查与摘要设计稿当你接手一个陌生的 Figma 文件或者想快速了解一个页面的结构时不需要手动滚动和点击。你可以对 AI 说“请列出当前文件的所有页面。” 或 “获取页面 ‘Home’ 中所有画板的名称和尺寸。”背后调用的工具很可能是list_pages和get_page_nodes。list_pages对应 Figma API 的GET /v1/files/:key返回文件的基本信息其中包含页面列表。get_page_nodes可能对应GET /v1/files/:key/nodes?ids...通过传入页面 ID 或节点 ID获取特定范围内节点的详细属性。AI 的操作流程AI 理解你的指令决定调用list_pages工具。通过 MCP 协议向你的figma-ui-mcp服务器发送请求。服务器使用令牌和文件 ID调用 Figma API。将返回的 JSON 数据页面名称、ID 等传回给 AI。AI 解析数据并以清晰的 Markdown 列表或表格形式呈现给你。实操心得对于大型文件直接获取所有节点详情可能会超时或返回数据巨大。好的 MCP 工具设计会提供过滤参数比如只获取画板FRAME类型的节点或者限制返回的字段。你可以要求 AI 进行摘要比如“用一句话描述每个页面的主要内容”这结合了 AI 的概括能力和 MCP 的数据获取能力。4.2 场景二批量修改设计属性这是自动化最实用的地方。比如产品经理说要把所有“警告”按钮的底色从橙色改为红色。你可以对 AI 说“找到所有名字包含 ‘warning’ 或 ‘alert’ 的按钮组件实例将它们的填充色改为 #EF4444。”背后调用的工具这可能需要组合多个工具。find_nodes通过名称或类型筛选节点。这可能需要服务器实现一个搜索逻辑遍历文件节点或利用 Figma API 的GET /v1/files/:key/nodes?ids...进行批量查询。update_fills修改节点的填充属性。对应 Figma API 的PUT /v1/files/:key中的document变更操作。AI 的操作流程AI 调用find_nodes传入搜索关键词获得一组节点 ID。对于每个找到的节点 IDAI 构造一个update_fills请求指定新的颜色值。这里可能涉及颜色格式的转换从 HEX 到 Figma 接受的 RGBA 对象。服务器将这些更新操作批量或逐个发送给 Figma API。注意事项幂等性好的工具设计应保证同一操作执行多次结果不变。比如update_fills应该直接设置颜色而不是在当前颜色上叠加。错误处理如果部分节点更新失败如节点不存在或无权限工具应返回明确的错误信息而不是让整个批量操作静默失败。AI 客户端应能向用户报告部分成功的情况。确认机制对于重大修改在 AI 执行前可以要求它先列出将要修改的节点让你确认后再执行。这可以通过对话流程来实现。4.3 场景三从文本生成简单 UI 草图这是一个更前瞻的场景。你可以描述一个简单的 UI比如“一个登录框包含邮箱输入框、密码输入框和一个提交按钮垂直居中排列。”背后调用的工具这需要服务器实现一个更高级的create_ui_from_description工具它内部会分解为一系列原子操作创建画板Frame。创建文本图层Text作为输入框标签。创建矩形图层Rectangle作为输入框背景。创建按钮可以是组件实例或矩形文本组合。使用update_constraints或update_layout等工具如果 Figma API 支持或通过计算坐标来排列这些元素。当前限制Figma API 对创建复杂节点尤其是带自动布局的 Frame的支持是逐步完善的。早期的 API 可能只支持更新属性创建节点能力有限。从文本描述到精确的布局参数间距、大小需要 AI 有很强的空间理解能力或者依赖一套预设的设计规则如 8pt 网格系统。因此现阶段这个场景可能更多用于生成静态元素和修改完全从零生成复杂、精确的布局还比较困难但作为灵感草图和快速打样已经非常强大。5. 高级技巧与自定义扩展当你熟悉了基本操作后可以尝试更进阶的用法甚至根据自己的需求扩展这个 MCP 服务器。5.1 利用 AI 进行设计决策辅助MCP 提供了数据AI 拥有推理能力。你可以进行更复杂的问答设计系统检查“检查当前页面中所有文本图层的字体样式并列出所有未被我们设计系统定义的字体大小和颜色。”实现思路AI 先获取所有文本节点然后调用一个本地设计系统规则库可以是另一个资源或工具进行比对最后生成报告。对比分析“比较 ‘Home Page v1’ 和 ‘Home Page v2’ 两个画板在图层结构上的主要差异。”实现思路AI 分别获取两个画板的节点树然后进行递归比较找出增删改的节点。5.2 将 MCP 服务器集成到自动化流水线figma-ui-mcp不仅可以被交互式 AI 使用也可以作为脚本的一部分。设计稿变更同步在 CI/CD 流程中当 Figma 设计文件有更新时触发一个脚本。该脚本通过 MCP 服务器或直接调用其底层逻辑获取最新的设计属性如颜色、间距、字体并自动生成或更新对应的前端样式文件如 CSS 变量、Tailwind 配置。批量导出资产编写一个 Node.js 脚本模拟 MCP 客户端调用服务器提供的export_nodes工具如果实现了定期将 Figma 中的图标、插图批量导出为 SVG 或 PNG并推送到资源仓库。5.3 自定义工具开发指南如果现有的工具不满足你的需求你可以 Fork 原项目进行扩展。步骤通常如下理解 SDK仔细阅读modelcontextprotocol/sdk的文档了解如何定义Tool和Resource。分析现有代码查看项目中tools/目录下的现有工具实现理解它们如何包装 Figma API、处理输入参数和返回结果。添加新工具在工具定义文件中新增一个工具对象明确其name、description和inputSchema输入参数的 JSON Schema。清晰的描述和严谨的 Schema 能极大帮助 AI 理解何时以及如何调用你的工具。实现工具的处理函数。这个函数是异步的接收输入参数调用 Figma API处理响应并返回结构化的结果或错误。将新工具注册到服务器的工具列表中。测试你的工具不要只在 AI 里测试。可以先写一个简单的测试脚本直接调用你的工具函数确保其逻辑正确。然后再通过 Claude Desktop 等客户端进行集成测试。一个自定义工具示例批量重命名图层假设你需要一个根据正则表达式批量重命名图层的工具。// 伪代码示例 const renameLayersTool { name: rename_layers_by_pattern, description: 使用正则表达式匹配并替换图层名称。, inputSchema: { type: object, properties: { pageId: { type: string, description: 页面ID }, searchPattern: { type: string, description: 搜索的正则表达式 }, replacement: { type: string, description: 替换后的文本 }, }, required: [pageId, searchPattern, replacement], }, }; async function handleRenameLayers({ pageId, searchPattern, replacement }) { // 1. 调用 Figma API 获取该页面节点 // 2. 遍历节点对名称应用 regex replace // 3. 构造 Figma API 的更新请求体 // 4. 发送更新请求 // 5. 返回成功/失败计数 }6. 常见问题排查与性能优化在实际使用中你肯定会遇到一些问题。这里记录一些典型问题和解决思路。6.1 连接与认证问题问题现象可能原因排查步骤Claude 提示“无法连接 MCP 服务器”或“工具加载失败”。1. MCP 服务器进程未启动。2. Claude 配置中的命令路径错误。3. 服务器启动时抛出未捕获异常。1. 在终端手动运行node /path/to/server/index.js观察是否有错误输出。2. 检查 Claude 配置文件中的args路径确保是绝对路径且指向正确的文件。3. 查看服务器代码的日志确认是否成功读取了环境变量FIGMA_TOKEN等。AI 调用工具时返回“认证失败”或“无权限”。1. Figma 个人访问令牌无效或已撤销。2. 令牌没有访问目标文件的权限。3. 文件 ID 错误。1. 在 Figma 设置中检查令牌状态必要时重新生成。2. 确认运行服务器的环境变量中令牌是否正确设置。可以用echo $FIGMA_PERSONAL_ACCESS_TOKEN验证。3. 确认文件 ID 是否正确并且该文件对你令牌所属的账号可见。工具调用后长时间无响应或超时。1. Figma API 响应慢。2. 网络问题。3. 服务器处理复杂请求时阻塞。1. 尝试直接在浏览器中访问 Figma看是否网络正常。2. 服务器代码中是否对 Figma API 调用设置了合理的超时如 30秒。3. 对于获取大量节点的操作考虑分页或增量获取。6.2 API 限制与性能瓶颈Figma API 有速率限制免费账户限制更严格。无节制的调用很快就会触发限制。策略一缓存。对于不常变动的数据如文件结构、页面列表可以在服务器内存中设置短期缓存例如 5 分钟。这样 AI 多次询问“有哪些页面”时不会每次都触发 API 调用。策略二批量操作。设计工具时尽量支持批量更新。例如update_colors工具应该接受一个节点 ID 和颜色值的列表而不是让 AI 为每个节点单独调用一次工具。这减少了 HTTP 请求次数。策略三明智地选择节点。get_node工具应支持depth参数允许用户指定需要获取多少层子节点。获取整个文件的完整树结构通常是低效且不必要的。策略四异步处理。对于非常耗时的操作如导出所有画板工具可以设计成触发一个异步任务并立即返回一个任务 ID。然后提供另一个工具如get_export_status来查询结果。这避免了 HTTP 请求超时。6.3 工具设计的“坑”输入 Schema 过于宽松如果你的工具接受一个color参数定义为{type: “string”}AI 可能会传入 “blue”, “#00F”, “rgb(0,0,255)”。这会给服务器解析带来麻烦。最佳实践是定义更严格的 Schema或是在工具内部做兼容性转换并给出清晰的错误提示。错误信息不友好当 Figma API 返回错误时不要直接把原始的、可能很长的 JSON 错误扔给 AI。应该提取关键信息如 “Node with id ‘123’ not found”并以清晰的结构化格式返回这样 AI 才能生成用户能理解的解释。工具粒度问题工具太细如set_x,set_y,set_width会导致完成一个简单任务需要多次来回对话体验差。工具太粗如redesign_pageAI 难以可靠使用实现也复杂。应从最常见的用户意图出发设计粒度适中的工具如align_nodes对齐节点、distribute_spacing分布间距。7. 安全实践与生产环境考量将这样一个能操作设计资产的服务运行起来安全不容忽视。令牌管理绝不硬编码令牌永远不要写在源代码里。使用环境变量在本地开发使用.env文件确保.env在.gitignore中。在服务器环境使用托管服务如 AWS Secrets Manager, GitHub Secrets的环境变量注入。最小权限原则如果可能创建权限范围更窄的令牌。但 Figma 目前的个人访问令牌是全权令牌因此更需要妥善保管。服务器访问控制figma-ui-mcp服务器本身如果以 HTTP 服务形式运行而非 stdio需要绑定到localhost或内部网络并设置防火墙规则防止公网直接访问。如果有多人使用考虑为每个用户/会话启动独立的服务器实例避免文件 ID 和操作混淆。操作审计与确认对于写操作修改、删除可以在工具层面或客户端层面增加确认机制。例如AI 在执行delete_nodes前必须明确列出即将删除的节点名称并等待用户输入“确认”后再执行。考虑在服务器端添加简单的日志功能记录谁通过哪个令牌在什么时间执行了什么操作。这对于团队协作和问题回溯至关重要。依赖与更新定期更新项目依赖npm update特别是modelcontextprotocol/sdk和 Figma API 客户端库以获取安全补丁和新功能。关注 Figma API 的版本更新和变更日志及时调整你的服务器代码避免因 API 废弃而导致服务中断。这个项目代表了 AI 与专业工具深度集成的一个非常具体的范例。它不再仅仅是聊天和生成文本而是成为了一个可行动的、能理解专业领域上下文的工作伙伴。虽然目前可能还有些粗糙会遇到速率限制、API 能力边界等问题但它清晰地指明了一个方向未来的创意工具其界面可能不仅仅是图形按钮和菜单还会包含一个能听懂你意图、并帮你执行的智能对话界面。