
1. 引言在前后端分离与设计系统驱动开发的今天一个高频痛点始终存在设计稿在 Figma 中已经完成但工程师仍需对照稿子手动还原样式、切图、翻译成组件代码。这个过程不仅耗时还容易因为肉眼误差造成「像素级」返工。MCPModel Context Protocol的出现提供了一种新的解法让 AI 助手能够通过统一协议直接读取 Figma 设计稿的节点信息、样式变量和布局数据再结合代码生成能力把「设计 → 代码」这条链路半自动化甚至全自动化。本文将深入拆解Huolala货拉拉开源的 Figma MCP的实现原理并配以可直接运行的代码实战带你从零跑通「读取设计稿 → 提取结构化数据 → 生成前端组件」的完整流程。2. 背景知识什么是 MCP2.1 MCP 的定义MCPModel Context Protocol模型上下文协议是 Anthropic 于 2024 年底开源的一套开放协议目标是解决大语言模型与外部工具、数据源之间的连接问题。它类比于 AI 领域的「USB-C 接口」只要工具方实现了 MCP任意支持 MCP 的客户端如 Claude Desktop、Cursor、各类自研 Agent都能以统一方式发现并调用这些工具。2.2 MCP 的核心角色MCP 采用典型的客户端-服务器架构包含三个角色Host宿主承载 AI 会话的应用例如 Claude Desktop、IDE 插件、聊天机器人。Client客户端在 Host 内部维护与 Server 的一对一连接。Server服务端暴露具体能力的程序可以操作数据库、浏览器、文件系统或者 Figma 设计稿。2.3 传输层MCP 支持多种传输方式常见的有stdio通过标准输入输出通信本地进程直连简单可靠。HTTP SSE适合远程服务部署通过 Server-Sent Events 推送消息。理解这套架构后再看 Figma MCP 就会清晰很多它本质上是一个实现了 MCP Server 协议、内部封装了 Figma API 的进程。3. Huolala Figma MCP 概述Huolala Figma MCP 是货拉拉技术团队开源的一个 MCP Server它把 Figma 的设计 API 包装成一组可供 LLM 调用的标准工具使 AI 助手能够读取 Figma 文件、画板Frame、组件节点获取节点的样式信息颜色、字体、圆角、阴影、布局等提取设计变量Design Tokens与组件实例结合提示词将结构化设计数据转换为前端代码如 Vue、React。它的核心价值在于把「看设计稿」这件事从模糊的图像理解升级为精准的结构化数据读取。相比直接截图给多模态模型读取 Figma API 返回的节点树与样式对象能获得精确到像素的尺寸、字号、颜色值生成的代码可用性大幅提升。4. 核心原理架构4.1 整体链路MCP 协议REST APIAI 客户端Claude / Cursor / 自研 AgentHuolala Figma MCP ServerFigma 官方 APIFigma 设计文件节点解析器结构化设计数据代码生成器前端组件代码4.2 工具注册机制MCP Server 启动时会向客户端声明自己的工具列表Tools。每个工具包含name工具名供模型调用description描述帮助模型判断何时调用inputSchema入参的 JSON Schema约束模型的传参结构。伪代码示意如下server.setRequestHandler(ListToolsRequestSchema,async()({tools:[{name:get_figma_file,description:获取 Figma 文件的完整节点树,inputSchema:{type:object,properties:{fileKey:{type:string},nodeId:{type:string},},required:[fileKey],},},],}));Client 侧拿到这份清单后LLM 就能在对话中按需选择并传入正确参数从而驱动后续的数据获取与代码生成。4.3 请求处理流程一次典型的「读取设计稿并生成组件」流程如下Figma APIFigma MCP ServerMCP Client用户 / LLM AgentFigma APIFigma MCP ServerMCP Client用户 / LLM Agent请读取该 Figma 节点并生成 React 组件调用 get_figma_nodeGET /v1/files/:key/nodes?ids:id返回节点 JSON结构化设计数据由 LLM 结合数据生成代码可以看到MCP Server 本身并不替代 LLM它只负责「取数」而「生成代码」这一步由 LLM 在拿到结构化数据后完成。这种分工既保证了数据准确性又保留了模型在代码风格上的灵活性。5. 环境准备开始实战前请准备以下环境5.1 基础依赖Node.js 20或对应语言的运行时npm / pnpm 包管理器一个 Figma 账号免费版即可一个支持 MCP 的客户端本文以 Claude Desktop 与 Cursor 为例5.2 获取 Figma Access Token登录 Figma 后进入Settings → Security → Personal access tokens点击「Generate new token」创建一个 Token并妥善保存。该 Token 用于调用 Figma REST API。5.3 获取 File Key打开目标 Figma 文件浏览器地址栏中的路径形如https://www.figma.com/design/XXXXXXXXXXXX/项目名?node-id1-2其中XXXXXXXXXXXX这一段就是 File Key。记录下它后续调用会频繁使用。6. 实战一配置并启动 MCP Server6.1 获取项目并安装依赖将 Huolala Figma MCP 项目克隆到本地以社区常见 Node 实现为例请以实际仓库为准gitclone https://github.com/your-org/huolala-figma-mcp.gitcdhuolala-figma-mcpnpminstall6.2 配置环境变量创建.env文件写入 Figma TokenFIGMA_ACCESS_TOKENfigd_xxxxxxxxxxxxxxxxxxxx6.3 在 Claude Desktop 中注册编辑 Claude Desktop 的配置文件claude_desktop_config.json{mcpServers:{huolala-figma-mcp:{command:node,args:[/绝对路径/huolala-figma-mcp/dist/index.js],env:{FIGMA_ACCESS_TOKEN:figd_xxxxxxxxxxxxxxxxxxxx}}}}重启 Claude Desktop若配置正确即可在工具列表中看到 Figma 相关工具。6.4 在 Cursor 中注册Cursor 1.x 已原生支持 MCP。在Settings → MCP → Add new MCP server中填写{name:huolala-figma-mcp,type:stdio,command:node /绝对路径/huolala-figma-mcp/dist/index.js,env:{FIGMA_ACCESS_TOKEN:figd_xxxxxxxxxxxxxxxxxxxx}}保存后即可在 Cursor 的 Chat / Agent 面板中使用。7. 实战二读取设计稿节点数据7.1 获取文件节点树通过 MCP 的get_figma_file工具可以获取整个文件的结构。若直接调用 REST API等价请求为curl-HX-Figma-Token:$FIGMA_ACCESS_TOKEN\https://api.figma.com/v1/files/你的FileKey返回的 JSON 中document.children是顶层画板列表styles则包含文件中定义的颜色、文本、效果样式。我们重点关注document节点树{name:Document,type:DOCUMENT,children:[{name:首页,type:FRAME,id:1:2,width:1440,height:900,children:[]}]}7.2 精准读取单个节点当文件较大时全量拉取会比较慢。此时可以用get_figma_node只获取目标节点curl-HX-Figma-Token:$FIGMA_ACCESS_TOKEN\https://api.figma.com/v1/files/你的FileKey/nodes?ids1:2返回结果中的nodes[1:2].document即该节点及其子树的完整信息。7.3 通过 Node.js 脚本完整演示下面的脚本展示了如何封装 Figma API 调用并递归解析出所有文本节点consttokenprocess.env.FIGMA_ACCESS_TOKEN;constfileKey你的FileKey;asyncfunctionfigmaFetch(path){constresawaitfetch(https://api.figma.com/v1${path},{headers:{X-Figma-Token:token},});if(!res.ok){thrownewError(Figma API 请求失败:${res.status});}returnres.json();}functionwalk(node,result[]){if(node.typeTEXT){result.push({id:node.id,text:node.characters,fontSize:node.style?.fontSize,color:node.fills?.[0]?.color,});}node.children?.forEach((child)walk(child,result));returnresult;}(async(){constdataawaitfigmaFetch(/files/${fileKey});consttextswalk(data.document);console.log(文本节点总数:,texts.length);console.log(JSON.stringify(texts.slice(0,10),null,2));})();这一步是后续代码生成的基础只有拿到精确的fontSize、color、width等属性生成的样式才不会「凭感觉」。8. 实战三生成前端组件代码8.1 结构化设计数据到组件假设我们从 Figma 中读到一个按钮节点数据如下{name:primary-button,type:FRAME,width:120,height:40,backgroundColor:{r:0.0,g:0.48,b:1.0,a:1.0},cornerRadius:8,children:[{name:label,type:TEXT,characters:立即下单,fontSize:14,textColor:{r:1,g:1,b:1,a:1}}]}我们可以写一个转换器把 Figma 的 0-1 颜色值转换为 CSS 可用的rgb()functionfigmaColorToCss(color{}){const{r0,g0,b0,a1}color;constround(v)Math.round(v*255);returnrgba(${round(r)},${round(g)},${round(b)},${a});}8.2 生成 React 组件结合模型生成能力最终产出可运行的 React 组件interface PrimaryButtonProps { children?: React.ReactNode; onClick?: () void; } export function PrimaryButton({ children 立即下单, onClick }: PrimaryButtonProps) { return ( button onClick{onClick} style{{ width: 120, height: 40, background: rgb(0, 122, 255), borderRadius: 8, color: #fff, fontSize: 14, border: none, cursor: pointer, }} {children} /button ); }8.3 生成 Vue 组件如果团队使用 Vue同样可以用结构化数据生成template button classprimary-button clickhandleClick slot立即下单/slot /button /template script setup langts const emit defineEmits{ (e: click): void }(); function handleClick() { emit(click); } /script style scoped .primary-button { width: 120px; height: 40px; background: rgb(0, 122, 255); border: none; border-radius: 8px; color: #fff; font-size: 14px; cursor: pointer; } /style8.4 在 Agent 中端到端调用在支持 MCP 的 Agent 中完整对话如下用户请读取 Figma 文件File Key: XXXX中 node-id 为 1:2 的画板 并按货拉拉小程序组件规范生成对应的组件代码。 Agent 执行过程 1. 调用 get_figma_node 获取节点 1:2 的结构化数据。 2. 识别节点类型、布局、颜色与文本。 3. 按团队代码规范生成组件代码。 4. 输出代码并说明对齐的具体样式值。这样「设计稿变更 → 代码同步」不再依赖人工比对。9. 进阶实践设计 Token 与多端适配9.1 提取设计变量大型项目中颜色、字号通常沉淀为 Design Tokens。Figma API 的files/:key返回中包含styles与variableCollections可据此生成团队的 token 文件constdataawaitfigmaFetch(/files/${fileKey});consttokensdata.styles;console.log(样式总数:,Object.keys(tokens).length);// 进一步遍历 variableCollections 提取变量关系生成的 token 文件示例:root{--color-brand:rgb(0,122,255);--color-text:rgb(51,51,51);--radius-md:8px;--font-size-md:14px;}9.2 多端Web / 小程序适配同样的设计节点可以针对不同端输出不同代码。关键在于在提示词或生成策略中注入平台约束系统提示节选 - Web 端使用 flex rem样式使用 CSS Modules。 - 小程序端使用 rpx 单位1px 2rpx 设计稿基准 750。 - 组件命名遵循 Huolala 组件规范导出需包含类型定义。这样同一份结构化数据即可生成多份符合各端规范的代码。10. 常见问题与排查10.1 Token 无权限报错403 Forbidden通常是 Token 权限不足或文件未共享给对应账号。请确认 Token 账户对目标文件有查看权限且 Token 类型具有file:read权限。10.2 节点 ID 格式问题Figma 节点 ID 形如1:2在 URL 中常被编码为1-2。API 调用时必须使用冒号格式1:2否则会返回404。10.3 图片导出灰度与失真若需要导出切图单独调用images/:key接口并指定formatpng与scale22 倍图避免使用截图导致模糊。10.4 大文件读取缓慢优先使用nodes接口按需读取目标节点而非全量拉取文件同时可在服务端增加缓存减少重复请求。11. 总结Huolala Figma MCP 把 Figma 的官方 API 封装为模型可调用的标准工具打通了「设计 → 数据 → 代码」的关键链路。相比传统的截图识别它提供的是可计算的、精确到像素的结构化数据让生成的组件代码在尺寸、颜色、排版上更接近设计原稿。本文从 MCP 基础概念出发拆解了 Figma MCP 的工具注册与请求处理原理并给出了配置启动、节点读取、代码生成、Token 提取与多端适配的完整实战。你可以基于这套范式结合团队自身的组件规范与设计系统进一步扩展出「设计稿变更自动提交代码评审」等更自动化的工程流程。建议动手实践时优先从一个简单画板开始验证整条链路再逐步接入真实业务组件让设计到开发的协作真正高效起来。