Figma UI 与 MCP 协议:用自然语言自动化设计工作流
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 协议返回给 AI,AI 最后以友好的格式呈现给你。
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_TOKEN=token FIGMA_FILE_ID=file_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。 - 对于每个找到的节点 ID,AI 构造一个
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_page),AI 难以可靠使用,实现也复杂。应从最常见的用户意图出发,设计粒度适中的工具,如align_nodes(对齐节点)、distribute_spacing(分布间距)。
7. 安全实践与生产环境考量
将这样一个能操作设计资产的服务运行起来,安全不容忽视。
- 令牌管理:
- 绝不硬编码:令牌永远不要写在源代码里。
- 使用环境变量:在本地开发使用
.env文件(确保.env在.gitignore中)。在服务器环境使用托管服务(如 AWS Secrets Manager, GitHub Secrets)的环境变量注入。 - 最小权限原则:如果可能,创建权限范围更窄的令牌。但 Figma 目前的个人访问令牌是全权令牌,因此更需要妥善保管。
- 服务器访问控制:
figma-ui-mcp服务器本身如果以 HTTP 服务形式运行(而非 stdio),需要绑定到localhost或内部网络,并设置防火墙规则,防止公网直接访问。- 如果有多人使用,考虑为每个用户/会话启动独立的服务器实例,避免文件 ID 和操作混淆。
- 操作审计与确认:
- 对于写操作(修改、删除),可以在工具层面或客户端层面增加确认机制。例如,AI 在执行
delete_nodes前,必须明确列出即将删除的节点名称,并等待用户输入“确认”后再执行。 - 考虑在服务器端添加简单的日志功能,记录谁(通过哪个令牌)在什么时间执行了什么操作。这对于团队协作和问题回溯至关重要。
- 对于写操作(修改、删除),可以在工具层面或客户端层面增加确认机制。例如,AI 在执行
- 依赖与更新:
- 定期更新项目依赖(
npm update),特别是@modelcontextprotocol/sdk和 Figma API 客户端库,以获取安全补丁和新功能。 - 关注 Figma API 的版本更新和变更日志,及时调整你的服务器代码,避免因 API 废弃而导致服务中断。
- 定期更新项目依赖(
这个项目代表了 AI 与专业工具深度集成的一个非常具体的范例。它不再仅仅是聊天和生成文本,而是成为了一个可行动的、能理解专业领域上下文的工作伙伴。虽然目前可能还有些粗糙,会遇到速率限制、API 能力边界等问题,但它清晰地指明了一个方向:未来的创意工具,其界面可能不仅仅是图形按钮和菜单,还会包含一个能听懂你意图、并帮你执行的智能对话界面。
