1. 引言

在前后端分离与设计系统驱动开发的今天，一个高频痛点始终存在：设计稿在 Figma 中已经完成，但工程师仍需对照稿子手动还原样式、切图、翻译成组件代码。这个过程不仅耗时，还容易因为肉眼误差造成「像素级」返工。

MCP（Model Context Protocol）的出现提供了一种新的解法：让 AI 助手能够通过统一协议直接读取 Figma 设计稿的节点信息、样式变量和布局数据，再结合代码生成能力，把「设计 → 代码」这条链路半自动化甚至全自动化。

本文将深入拆解Huolala（货拉拉）开源的 Figma MCP的实现原理，并配以可直接运行的代码实战，带你从零跑通「读取设计稿 → 提取结构化数据 → 生成前端组件」的完整流程。

2. 背景知识：什么是 MCP

2.1 MCP 的定义

MCP（Model 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 整体链路

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 请求处理流程

一次典型的「读取设计稿并生成组件」流程如下：

可以看到，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-id=1-2

其中XXXXXXXXXXXX这一段就是 File Key。记录下它，后续调用会频繁使用。

6. 实战一：配置并启动 MCP Server

6.1 获取项目并安装依赖

将 Huolala Figma MCP 项目克隆到本地（以社区常见 Node 实现为例，请以实际仓库为准）：

gitclone https://github.com/your-org/huolala-figma-mcp.gitcdhuolala-figma-mcpnpminstall

6.2 配置环境变量

创建.env文件，写入 Figma Token：

FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxxxxxxxxxx

6.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-H"X-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-H"X-Figma-Token:$FIGMA_ACCESS_TOKEN"\"https://api.figma.com/v1/files/你的FileKey/nodes?ids=1:2"

返回结果中的nodes["1:2"].document即该节点及其子树的完整信息。

7.3 通过 Node.js 脚本完整演示

下面的脚本展示了如何封装 Figma API 调用，并递归解析出所有文本节点：

consttoken=process.env.FIGMA_ACCESS_TOKEN;constfileKey="你的FileKey";asyncfunctionfigmaFetch(path){constres=awaitfetch(`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.type==="TEXT"){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()=>{constdata=awaitfigmaFetch(`/files/${fileKey}`);consttexts=walk(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{r=0,g=0,b=0,a=1}=color;constround=(v)=>Math.round(v*255);return`rgba(${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 class="primary-button" @click="handleClick"> <slot>立即下单</slot> </button> </template> <script setup lang="ts"> 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; } </style>

8.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 文件：

constdata=awaitfigmaFetch(`/files/${fileKey}`);consttokens=data.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接口，并指定format=png与scale=2（2 倍图），避免使用截图导致模糊。

10.4 大文件读取缓慢

优先使用nodes接口按需读取目标节点，而非全量拉取文件；同时可在服务端增加缓存，减少重复请求。

11. 总结

Huolala Figma MCP 把 Figma 的官方 API 封装为模型可调用的标准工具，打通了「设计 → 数据 → 代码」的关键链路。相比传统的截图识别，它提供的是可计算的、精确到像素的结构化数据，让生成的组件代码在尺寸、颜色、排版上更接近设计原稿。

本文从 MCP 基础概念出发，拆解了 Figma MCP 的工具注册与请求处理原理，并给出了配置启动、节点读取、代码生成、Token 提取与多端适配的完整实战。你可以基于这套范式，结合团队自身的组件规范与设计系统，进一步扩展出「设计稿变更自动提交代码评审」等更自动化的工程流程。

建议动手实践时，优先从一个简单画板开始验证整条链路，再逐步接入真实业务组件，让设计到开发的协作真正高效起来。