最近在尝试将AI助手集成到前端设计开发流程中发现一个痛点设计师在Figma中完成的设计稿开发同学需要手动测量、复制属性或者依赖第三方插件导出过程繁琐且容易出错。如果能让AI直接“看懂”Figma设计稿的结构和属性自动生成代码或分析报告效率将大大提升。本文将围绕Figma MCP (Model Context Protocol)和Codex这两个核心工具手把手带你实现一个实战项目让AI通过MCP协议读取Figma设计节点并一次性获取完整的JSON结构数据。无论你是想探索AI设计的新玩法还是希望优化团队的设计交付流程这篇文章都将提供从原理到代码的完整闭环方案。1. 背景与核心概念为什么需要MCP连接Figma与AI在深入代码之前我们有必要厘清几个关键概念理解它们如何串联起整个工作流。1.1 Figma不仅仅是设计工具Figma早已超越传统的UI设计软件其核心价值在于云端协作和开放的API生态。通过Figma API开发者可以以编程方式访问文件、图层、组件等几乎所有设计数据。这为自动化流程如设计稿检查、资产导出、代码生成提供了可能。1.2 MCP (Model Context Protocol)AI的“统一数据总线”MCP是由Anthropic等公司推动的一个开放协议你可以把它理解为AI助手如Claude、Cursor等与外部工具、数据源之间的“通用连接器”。在没有MCP之前如果你想用AI分析公司内部数据可能需要为每个AI平台Claude Desktop, Cursor, Windsurf等单独开发插件工作重复且割裂。MCP的目标是定义一套标准协议让开发者只需编写一次“MCP Server”即数据提供方就能让所有支持MCP协议的“MCP Client”即AI应用来调用。核心组件MCP Server服务器提供数据和能力的后端服务。本文中我们将创建一个能读取Figma数据的MCP Server。MCP Client客户端消费这些数据和能力的AI应用如Claude Desktop。Tools工具Server暴露给Client的可调用函数例如get_figma_file。Resources资源Server提供的可读数据URI例如figma://file/{file_id}。1.3 Codex本文的“AI客户端”代表在搜索热词中频繁出现的“Codex”在这里并非特指OpenAI的Codex模型而是泛指一类支持通过MCP协议接入外部工具的AI代码助手或应用。它可能是某个定制化的开发环境或者是集成了MCP Client的AI助手。在本文的语境下你可以将“Codex”理解为我们将要配置的、能够调用我们编写的Figma MCP Server的那个AI客户端。1.4 我们的目标构建 Figma → MCP Server → AI Client 的数据管道整个流程的架构如下数据源Figma设计文件通过Figma REST API访问。桥梁我们编写的Figma MCP Server使用Node.js/Python它封装了对Figma API的调用并通过MCP协议暴露数据。消费者配置好的AI客户端如Claude Desktop它通过MCP协议发现并调用我们的Server提供的工具。结果AI能够直接获取Figma节点的完整JSON结构并基于此进行对话、分析或生成代码。2. 环境准备与版本说明开始编码前请确保你的开发环境已就绪。2.1 基础环境要求操作系统macOS, Linux, 或 Windows (WSL2推荐)。Node.js版本 18 或更高。这是运行我们MCP Server的推荐环境。包管理器npm 或 yarn。代码编辑器VS Code。AI客户端我们将以Claude Desktop为例进行配置因为它对MCP的支持比较友好。请确保已安装。2.2 获取Figma访问凭证Figma MCP Server的核心是调用Figma API因此你需要一个Figma个人访问令牌Personal Access Token。登录 Figma官网 。点击右上角个人头像进入 “Settings”。在左侧找到 “Account” 标签页下的 “Personal access tokens”。点击 “Create new token”为其命名如MCP-Server并勾选必要的权限。对于读取文件内容通常需要file_read权限。点击 “Create”。重要立即复制生成的令牌字符串。它只显示一次请妥善保存例如放入环境变量。2.3 初始化项目创建一个新的项目目录并初始化。mkdir figma-mcp-server cd figma-mcp-server npm init -y3. 核心工具与库介绍我们将使用modelcontextprotocol/sdk来快速构建MCP Server。这是由Anthropic官方维护的SDK支持Node.js能极大简化开发。安装所需依赖npm install modelcontextprotocol/sdk node-fetchmodelcontextprotocol/sdkMCP协议的核心SDK。node-fetch用于发起HTTP请求到Figma API。4. 构建Figma MCP Server完整代码实战我们的Server主要提供两个核心能力1) 列出Figma文件2) 获取指定文件的完整节点树JSON。4.1 项目结构创建以下文件结构figma-mcp-server/ ├── index.js # MCP Server主入口文件 ├── figma-client.js # 封装Figma API调用的客户端 ├── .env # 存储环境变量如FIGMA_TOKEN └── package.json4.2 创建Figma API客户端首先我们封装一个简单的Figma API客户端用于处理认证和请求。文件figma-client.jsimport fetch from node-fetch; class FigmaClient { constructor(accessToken) { this.accessToken accessToken; this.baseUrl https://api.figma.com/v1; this.headers { X-Figma-Token: this.accessToken, }; } // 获取用户的所有项目团队下的项目 async getProjects(teamId) { const response await fetch(${this.baseUrl}/teams/${teamId}/projects, { headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } // 获取项目下的所有文件 async getProjectFiles(projectId) { const response await fetch(${this.baseUrl}/projects/${projectId}/files, { headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } // 获取文件的完整节点树JSON结构 async getFileNodes(fileId) { // geometrypaths 参数可以获取图形的矢量路径信息根据需要添加 const response await fetch(${this.baseUrl}/files/${fileId}?depth1, { // depth控制返回层级 headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } // 获取文件的特定节点通过node ids async getFileNode(fileId, nodeIds) { const ids Array.isArray(nodeIds) ? nodeIds.join(,) : nodeIds; const response await fetch(${this.baseUrl}/files/${fileId}/nodes?ids${ids}, { headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } } export default FigmaClient;4.3 创建MCP Server主文件这是核心我们定义Server提供的Tools。文件index.jsimport { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import FigmaClient from ./figma-client.js; import dotenv from dotenv; // 加载环境变量 dotenv.config(); const FIGMA_ACCESS_TOKEN process.env.FIGMA_TOKEN; if (!FIGMA_ACCESS_TOKEN) { console.error(错误未设置 FIGMA_TOKEN 环境变量。请在 .env 文件中配置。); process.exit(1); } // 初始化Figma客户端 const figmaClient new FigmaClient(FIGMA_ACCESS_TOKEN); // 创建MCP Server实例 const server new Server( { name: figma-mcp-server, version: 0.1.0, }, { capabilities: { tools: {}, // 声明本Server提供Tools }, } ); // 定义Tool获取Figma文件列表 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_figma_files, description: 获取指定Figma项目下的所有文件列表。需要提供团队ID和项目ID。, inputSchema: { type: object, properties: { teamId: { type: string, description: Figma团队ID。可以在Figma URL或团队设置中找到。, }, projectId: { type: string, description: Figma项目ID。可以在项目页面的URL中找到。, }, }, required: [teamId, projectId], }, }, { name: get_figma_file_nodes, description: 获取指定Figma文件的完整节点树结构JSON格式。, inputSchema: { type: object, properties: { fileId: { type: string, description: Figma文件ID。可以从文件分享链接或API获取。, }, }, required: [fileId], }, }, ], }; }); // 处理Tool调用获取文件列表 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name get_figma_files) { const { teamId, projectId } args; try { const files await figmaClient.getProjectFiles(projectId); // 格式化返回便于AI阅读 const fileList files.files.map(file ({ name: file.name, key: file.key, last_modified: file.last_modified, thumbnail_url: file.thumbnail_url, })); return { content: [ { type: text, text: 项目中共有 ${fileList.length} 个文件\n JSON.stringify(fileList, null, 2), }, ], }; } catch (error) { return { content: [ { type: text, text: 调用Figma API失败${error.message}, }, ], isError: true, }; } } if (name get_figma_file_nodes) { const { fileId } args; try { // 这里获取整个文件的节点树depth1获取第一层子节点可根据需要调整 const fileData await figmaClient.getFileNodes(fileId); // 返回完整的JSON结构这是AI进行分析的原材料 return { content: [ { type: text, // 使用text格式返回JSON字符串AI可以解析 text: 文件 ${fileData.name} 的节点结构如下\n json\n JSON.stringify(fileData, null, 2) \n, }, ], }; } catch (error) { return { content: [ { type: text, text: 获取文件节点失败${error.message}, }, ], isError: true, }; } } // 如果调用了未定义的Tool return { content: [ { type: text, text: 未知的工具调用${name}, }, ], isError: true, }; }); // 启动Server使用stdio传输与Claude Desktop等客户端通信的标准方式 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(Figma MCP Server 已启动正在等待客户端连接...); } main().catch((error) { console.error(Server启动失败:, error); process.exit(1); });4.4 配置环境变量在项目根目录创建.env文件填入你的Figma令牌。文件.envFIGMA_TOKEN你的Figma个人访问令牌重要确保将.env添加到.gitignore中避免令牌泄露。4.5 更新Package.json确保package.json中设置了type: module因为我们使用了ES6模块语法。{ name: figma-mcp-server, version: 0.1.0, description: A MCP server for accessing Figma design data., type: module, main: index.js, scripts: { start: node index.js }, dependencies: { modelcontextprotocol/sdk: ^0.5.0, dotenv: ^16.4.5, node-fetch: ^3.3.2 }, engines: { node: 18 } }5. 配置AI客户端以Claude Desktop为例我们的Server已经写好现在需要让AI客户端知道它的存在。5.1 获取Figma团队和项目ID登录Figma进入你的团队空间。点击一个项目。浏览器地址栏的URL格式通常为https://www.figma.com/files/team/团队ID/project/项目ID/...。从中提取团队ID和项目ID。点击项目内的一个文件。文件分享链接格式为https://www.figma.com/design/文件ID/...。从中提取文件ID。5.2 配置Claude DesktopClaude Desktop通过一个JSON配置文件来添加MCP Server。找到Claude Desktop的配置文件夹macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件不存在则创建它。如果存在在mcpServers字段中添加我们的Server配置。配置文件示例claude_desktop_config.json{ mcpServers: { figma: { command: node, args: [ /你的绝对路径/figma-mcp-server/index.js ], env: { FIGMA_TOKEN: 你的Figma个人访问令牌 } } } }配置说明figma给这个Server起一个名字你可以在Claude中通过这个名字调用它。command: 启动Server的命令这里是node。args: 命令的参数即我们Server主文件的绝对路径。env: 传递给Server进程的环境变量。这里我们直接传递FIGMA_TOKEN避免了在Server代码中硬编码或读取本地.env文件。保存配置文件并完全重启Claude Desktop。6. 运行与验证在AI对话中调用Figma数据重启Claude Desktop后新建一个对话。测试连接你可以直接问“你现在可以使用哪些MCP工具” Claude应该会列出它发现的工具其中包含我们定义的get_figma_files和get_figma_file_nodes。获取文件列表向Claude发出指令例如“请使用get_figma_files工具团队ID是1234567890项目ID是9876543210。”Claude会调用该工具并返回指定项目下的文件列表JSON。获取设计节点JSON从文件列表中拿到一个fileId然后让Claude获取其节点结构“请使用get_figma_file_nodes工具获取文件ID为ABCdefGHIjklMNop的完整节点结构。”结果分析Claude将返回一个格式化的、包含完整设计节点信息的JSON代码块。这个JSON包含了画布CANVAS、框架FRAME、组件COMPONENT、实例INSTANCE、图形RECTANGLE, ELLIPSE、文本TEXT等所有节点的层级、位置、样式、约束等属性。一个成功的响应示例片段文件 登录页设计 的节点结构如下 json { name: 登录页设计, lastModified: 2024-05-27T10:30:00Z, thumbnailUrl: ..., document: { id: 0:0, name: Document, type: DOCUMENT, children: [ { id: 1:1, name: 登录页面, type: CANVAS, backgroundColor: { r: 1, g: 1, b: 1, a: 1 }, children: [ { id: 2:2, name: Header, type: FRAME, absoluteBoundingBox: { x: 100, y: 50, width: 1200, height: 80 }, fills: [...], children: [ { id: 3:3, name: Logo, type: TEXT, characters: MyApp, style: { fontFamily: Inter, fontWeight: 700, fontSize: 24, fills: [...] } } ] } ] } ] } }现在AI已经能够“看到”你的设计稿了你可以继续要求它“基于这个JSON总结一下这个页面的配色方案和字体使用情况”或者“为这个按钮组件生成React代码”。 ## 7. 常见问题与排查思路 在搭建和使用过程中你可能会遇到以下问题 | 问题现象 | 可能原因 | 排查步骤与解决方案 | | :--- | :--- | :--- | | Claude Desktop 启动后提示找不到MCP Server或工具。 | 1. 配置文件路径错误。br2. 配置文件格式错误JSON语法。br3. Claude Desktop未重启。 | 1. 检查 claude_desktop_config.json 文件路径是否正确。br2. 使用 [JSONLint](https://jsonlint.com/) 验证配置文件格式。br3. **完全退出并重启Claude Desktop**。 | | 调用工具时返回“权限错误”或“无效令牌”。 | 1. Figma令牌无效或已过期。br2. 令牌权限不足缺少file_read。br3. 环境变量未正确传递。 | 1. 在Figma设置中重新生成令牌。br2. 确认令牌创建时勾选了 file_read 权限。br3. 检查Server启动命令中的env配置或确保本地.env文件已加载。 | | 调用 get_figma_files 成功但返回空列表。 | 1. 提供的 teamId 或 projectId 错误。br2. 该令牌无法访问指定的团队或项目。 | 1. 再次从Figma URL核对ID。br2. 确保生成该令牌的账号是目标团队/项目的成员。 | | 获取的节点JSON数据不完整或缺少属性。 | 1. Figma API调用时未指定需要的参数。br2. 文件过大API返回被截断。 | 1. 查看Figma API文档在 getFileNodes 方法中添加所需查询参数如 ?geometrypaths 获取路径数据。br2. 对于大文件考虑分节点node ids查询或增加请求超时时间。 | | Server启动失败报错 Cannot find package ...。 | 项目依赖未安装。 | 在项目根目录运行 npm install。 | | Node.js 报语法错误如 import 报错。 | package.json 中未设置 type: module或Node版本过低。 | 1. 确认 package.json 包含 type: module。br2. 运行 node -v 检查版本确保是Node 18。 | ## 8. 最佳实践与工程建议 将Figma MCP Server投入生产或团队协作环境时需要考虑以下几点 ### 8.1 安全性增强 * **令牌管理**绝对不要将令牌硬编码在代码或提交到版本库。使用环境变量或安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault。 * **权限最小化**为MCP Server创建专用的Figma账号并生成令牌仅授予其完成工作所必需的 file_read 权限避免使用高权限的主账号令牌。 * **访问控制**可以在MCP Server层增加简单的认证逻辑如允许列表只响应来自受信任客户端如特定IP或带有密钥的请求的调用。 ### 8.2 性能与稳定性 * **缓存策略**Figma设计文件不会频繁变动。可以在Server端对 getFileNodes 的结果进行缓存例如使用内存缓存如node-cache或Redis设置合理的TTL如5分钟避免对Figma API的频繁请求提升响应速度并遵守API速率限制。 * **错误处理与重试**在 figma-client.js 中增加更健壮的错误处理和指数退避重试机制应对网络波动或Figma API临时不可用。 * **分页与增量获取**对于节点数量巨大的文件一次性获取所有数据可能超时或超限。可以改造Tool支持分页或按节点ID范围查询。 ### 8.3 功能扩展 * **更多Tools**根据团队需求暴露更多Figma API能力。 * get_component_sets: 获取所有组件集。 * get_file_styles: 获取文件中定义的样式颜色、文本、效果。 * get_image_fills: 获取图片资源链接。 * **数据预处理与格式化**直接返回原始Figma JSON对AI来说信息量可能过大。可以在Server端进行预处理提取AI更关心的关键信息如组件关系、样式变量、布局约束并格式化为更简洁的结构返回提高AI处理效率和准确性。 * **支持更多AI客户端**除了Claude Desktop可以研究如何配置到Cursor、Windsurf等其他支持MCP的IDE或工具中。 ### 8.4 部署与协作 * **打包与分发**可以将Server打包成Docker镜像方便在不同环境中部署。 * **团队共享**将配置好的MCP Server和Claude Desktop配置文档化让团队其他成员也能一键接入统一设计数据源。 通过本文的实战你已经成功搭建了一座连接Figma设计世界与AI智能体的桥梁。这套方案不仅限于自动生成代码更打开了思路你可以让AI评审设计一致性、计算设计系统覆盖率、甚至基于设计数据生成产品需求文档。 基于MCP协议构建Figma数据管道：让AI直接读取设计稿JSON结构
最近在尝试将AI助手集成到前端设计开发流程中发现一个痛点设计师在Figma中完成的设计稿开发同学需要手动测量、复制属性或者依赖第三方插件导出过程繁琐且容易出错。如果能让AI直接“看懂”Figma设计稿的结构和属性自动生成代码或分析报告效率将大大提升。本文将围绕Figma MCP (Model Context Protocol)和Codex这两个核心工具手把手带你实现一个实战项目让AI通过MCP协议读取Figma设计节点并一次性获取完整的JSON结构数据。无论你是想探索AI设计的新玩法还是希望优化团队的设计交付流程这篇文章都将提供从原理到代码的完整闭环方案。1. 背景与核心概念为什么需要MCP连接Figma与AI在深入代码之前我们有必要厘清几个关键概念理解它们如何串联起整个工作流。1.1 Figma不仅仅是设计工具Figma早已超越传统的UI设计软件其核心价值在于云端协作和开放的API生态。通过Figma API开发者可以以编程方式访问文件、图层、组件等几乎所有设计数据。这为自动化流程如设计稿检查、资产导出、代码生成提供了可能。1.2 MCP (Model Context Protocol)AI的“统一数据总线”MCP是由Anthropic等公司推动的一个开放协议你可以把它理解为AI助手如Claude、Cursor等与外部工具、数据源之间的“通用连接器”。在没有MCP之前如果你想用AI分析公司内部数据可能需要为每个AI平台Claude Desktop, Cursor, Windsurf等单独开发插件工作重复且割裂。MCP的目标是定义一套标准协议让开发者只需编写一次“MCP Server”即数据提供方就能让所有支持MCP协议的“MCP Client”即AI应用来调用。核心组件MCP Server服务器提供数据和能力的后端服务。本文中我们将创建一个能读取Figma数据的MCP Server。MCP Client客户端消费这些数据和能力的AI应用如Claude Desktop。Tools工具Server暴露给Client的可调用函数例如get_figma_file。Resources资源Server提供的可读数据URI例如figma://file/{file_id}。1.3 Codex本文的“AI客户端”代表在搜索热词中频繁出现的“Codex”在这里并非特指OpenAI的Codex模型而是泛指一类支持通过MCP协议接入外部工具的AI代码助手或应用。它可能是某个定制化的开发环境或者是集成了MCP Client的AI助手。在本文的语境下你可以将“Codex”理解为我们将要配置的、能够调用我们编写的Figma MCP Server的那个AI客户端。1.4 我们的目标构建 Figma → MCP Server → AI Client 的数据管道整个流程的架构如下数据源Figma设计文件通过Figma REST API访问。桥梁我们编写的Figma MCP Server使用Node.js/Python它封装了对Figma API的调用并通过MCP协议暴露数据。消费者配置好的AI客户端如Claude Desktop它通过MCP协议发现并调用我们的Server提供的工具。结果AI能够直接获取Figma节点的完整JSON结构并基于此进行对话、分析或生成代码。2. 环境准备与版本说明开始编码前请确保你的开发环境已就绪。2.1 基础环境要求操作系统macOS, Linux, 或 Windows (WSL2推荐)。Node.js版本 18 或更高。这是运行我们MCP Server的推荐环境。包管理器npm 或 yarn。代码编辑器VS Code。AI客户端我们将以Claude Desktop为例进行配置因为它对MCP的支持比较友好。请确保已安装。2.2 获取Figma访问凭证Figma MCP Server的核心是调用Figma API因此你需要一个Figma个人访问令牌Personal Access Token。登录 Figma官网 。点击右上角个人头像进入 “Settings”。在左侧找到 “Account” 标签页下的 “Personal access tokens”。点击 “Create new token”为其命名如MCP-Server并勾选必要的权限。对于读取文件内容通常需要file_read权限。点击 “Create”。重要立即复制生成的令牌字符串。它只显示一次请妥善保存例如放入环境变量。2.3 初始化项目创建一个新的项目目录并初始化。mkdir figma-mcp-server cd figma-mcp-server npm init -y3. 核心工具与库介绍我们将使用modelcontextprotocol/sdk来快速构建MCP Server。这是由Anthropic官方维护的SDK支持Node.js能极大简化开发。安装所需依赖npm install modelcontextprotocol/sdk node-fetchmodelcontextprotocol/sdkMCP协议的核心SDK。node-fetch用于发起HTTP请求到Figma API。4. 构建Figma MCP Server完整代码实战我们的Server主要提供两个核心能力1) 列出Figma文件2) 获取指定文件的完整节点树JSON。4.1 项目结构创建以下文件结构figma-mcp-server/ ├── index.js # MCP Server主入口文件 ├── figma-client.js # 封装Figma API调用的客户端 ├── .env # 存储环境变量如FIGMA_TOKEN └── package.json4.2 创建Figma API客户端首先我们封装一个简单的Figma API客户端用于处理认证和请求。文件figma-client.jsimport fetch from node-fetch; class FigmaClient { constructor(accessToken) { this.accessToken accessToken; this.baseUrl https://api.figma.com/v1; this.headers { X-Figma-Token: this.accessToken, }; } // 获取用户的所有项目团队下的项目 async getProjects(teamId) { const response await fetch(${this.baseUrl}/teams/${teamId}/projects, { headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } // 获取项目下的所有文件 async getProjectFiles(projectId) { const response await fetch(${this.baseUrl}/projects/${projectId}/files, { headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } // 获取文件的完整节点树JSON结构 async getFileNodes(fileId) { // geometrypaths 参数可以获取图形的矢量路径信息根据需要添加 const response await fetch(${this.baseUrl}/files/${fileId}?depth1, { // depth控制返回层级 headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } // 获取文件的特定节点通过node ids async getFileNode(fileId, nodeIds) { const ids Array.isArray(nodeIds) ? nodeIds.join(,) : nodeIds; const response await fetch(${this.baseUrl}/files/${fileId}/nodes?ids${ids}, { headers: this.headers, }); if (!response.ok) { throw new Error(Figma API error: ${response.status} ${response.statusText}); } return await response.json(); } } export default FigmaClient;4.3 创建MCP Server主文件这是核心我们定义Server提供的Tools。文件index.jsimport { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import FigmaClient from ./figma-client.js; import dotenv from dotenv; // 加载环境变量 dotenv.config(); const FIGMA_ACCESS_TOKEN process.env.FIGMA_TOKEN; if (!FIGMA_ACCESS_TOKEN) { console.error(错误未设置 FIGMA_TOKEN 环境变量。请在 .env 文件中配置。); process.exit(1); } // 初始化Figma客户端 const figmaClient new FigmaClient(FIGMA_ACCESS_TOKEN); // 创建MCP Server实例 const server new Server( { name: figma-mcp-server, version: 0.1.0, }, { capabilities: { tools: {}, // 声明本Server提供Tools }, } ); // 定义Tool获取Figma文件列表 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_figma_files, description: 获取指定Figma项目下的所有文件列表。需要提供团队ID和项目ID。, inputSchema: { type: object, properties: { teamId: { type: string, description: Figma团队ID。可以在Figma URL或团队设置中找到。, }, projectId: { type: string, description: Figma项目ID。可以在项目页面的URL中找到。, }, }, required: [teamId, projectId], }, }, { name: get_figma_file_nodes, description: 获取指定Figma文件的完整节点树结构JSON格式。, inputSchema: { type: object, properties: { fileId: { type: string, description: Figma文件ID。可以从文件分享链接或API获取。, }, }, required: [fileId], }, }, ], }; }); // 处理Tool调用获取文件列表 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name get_figma_files) { const { teamId, projectId } args; try { const files await figmaClient.getProjectFiles(projectId); // 格式化返回便于AI阅读 const fileList files.files.map(file ({ name: file.name, key: file.key, last_modified: file.last_modified, thumbnail_url: file.thumbnail_url, })); return { content: [ { type: text, text: 项目中共有 ${fileList.length} 个文件\n JSON.stringify(fileList, null, 2), }, ], }; } catch (error) { return { content: [ { type: text, text: 调用Figma API失败${error.message}, }, ], isError: true, }; } } if (name get_figma_file_nodes) { const { fileId } args; try { // 这里获取整个文件的节点树depth1获取第一层子节点可根据需要调整 const fileData await figmaClient.getFileNodes(fileId); // 返回完整的JSON结构这是AI进行分析的原材料 return { content: [ { type: text, // 使用text格式返回JSON字符串AI可以解析 text: 文件 ${fileData.name} 的节点结构如下\n json\n JSON.stringify(fileData, null, 2) \n, }, ], }; } catch (error) { return { content: [ { type: text, text: 获取文件节点失败${error.message}, }, ], isError: true, }; } } // 如果调用了未定义的Tool return { content: [ { type: text, text: 未知的工具调用${name}, }, ], isError: true, }; }); // 启动Server使用stdio传输与Claude Desktop等客户端通信的标准方式 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(Figma MCP Server 已启动正在等待客户端连接...); } main().catch((error) { console.error(Server启动失败:, error); process.exit(1); });4.4 配置环境变量在项目根目录创建.env文件填入你的Figma令牌。文件.envFIGMA_TOKEN你的Figma个人访问令牌重要确保将.env添加到.gitignore中避免令牌泄露。4.5 更新Package.json确保package.json中设置了type: module因为我们使用了ES6模块语法。{ name: figma-mcp-server, version: 0.1.0, description: A MCP server for accessing Figma design data., type: module, main: index.js, scripts: { start: node index.js }, dependencies: { modelcontextprotocol/sdk: ^0.5.0, dotenv: ^16.4.5, node-fetch: ^3.3.2 }, engines: { node: 18 } }5. 配置AI客户端以Claude Desktop为例我们的Server已经写好现在需要让AI客户端知道它的存在。5.1 获取Figma团队和项目ID登录Figma进入你的团队空间。点击一个项目。浏览器地址栏的URL格式通常为https://www.figma.com/files/team/团队ID/project/项目ID/...。从中提取团队ID和项目ID。点击项目内的一个文件。文件分享链接格式为https://www.figma.com/design/文件ID/...。从中提取文件ID。5.2 配置Claude DesktopClaude Desktop通过一个JSON配置文件来添加MCP Server。找到Claude Desktop的配置文件夹macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件不存在则创建它。如果存在在mcpServers字段中添加我们的Server配置。配置文件示例claude_desktop_config.json{ mcpServers: { figma: { command: node, args: [ /你的绝对路径/figma-mcp-server/index.js ], env: { FIGMA_TOKEN: 你的Figma个人访问令牌 } } } }配置说明figma给这个Server起一个名字你可以在Claude中通过这个名字调用它。command: 启动Server的命令这里是node。args: 命令的参数即我们Server主文件的绝对路径。env: 传递给Server进程的环境变量。这里我们直接传递FIGMA_TOKEN避免了在Server代码中硬编码或读取本地.env文件。保存配置文件并完全重启Claude Desktop。6. 运行与验证在AI对话中调用Figma数据重启Claude Desktop后新建一个对话。测试连接你可以直接问“你现在可以使用哪些MCP工具” Claude应该会列出它发现的工具其中包含我们定义的get_figma_files和get_figma_file_nodes。获取文件列表向Claude发出指令例如“请使用get_figma_files工具团队ID是1234567890项目ID是9876543210。”Claude会调用该工具并返回指定项目下的文件列表JSON。获取设计节点JSON从文件列表中拿到一个fileId然后让Claude获取其节点结构“请使用get_figma_file_nodes工具获取文件ID为ABCdefGHIjklMNop的完整节点结构。”结果分析Claude将返回一个格式化的、包含完整设计节点信息的JSON代码块。这个JSON包含了画布CANVAS、框架FRAME、组件COMPONENT、实例INSTANCE、图形RECTANGLE, ELLIPSE、文本TEXT等所有节点的层级、位置、样式、约束等属性。一个成功的响应示例片段文件 登录页设计 的节点结构如下 json { name: 登录页设计, lastModified: 2024-05-27T10:30:00Z, thumbnailUrl: ..., document: { id: 0:0, name: Document, type: DOCUMENT, children: [ { id: 1:1, name: 登录页面, type: CANVAS, backgroundColor: { r: 1, g: 1, b: 1, a: 1 }, children: [ { id: 2:2, name: Header, type: FRAME, absoluteBoundingBox: { x: 100, y: 50, width: 1200, height: 80 }, fills: [...], children: [ { id: 3:3, name: Logo, type: TEXT, characters: MyApp, style: { fontFamily: Inter, fontWeight: 700, fontSize: 24, fills: [...] } } ] } ] } ] } }现在AI已经能够“看到”你的设计稿了你可以继续要求它“基于这个JSON总结一下这个页面的配色方案和字体使用情况”或者“为这个按钮组件生成React代码”。 ## 7. 常见问题与排查思路 在搭建和使用过程中你可能会遇到以下问题 | 问题现象 | 可能原因 | 排查步骤与解决方案 | | :--- | :--- | :--- | | Claude Desktop 启动后提示找不到MCP Server或工具。 | 1. 配置文件路径错误。br2. 配置文件格式错误JSON语法。br3. Claude Desktop未重启。 | 1. 检查 claude_desktop_config.json 文件路径是否正确。br2. 使用 [JSONLint](https://jsonlint.com/) 验证配置文件格式。br3. **完全退出并重启Claude Desktop**。 | | 调用工具时返回“权限错误”或“无效令牌”。 | 1. Figma令牌无效或已过期。br2. 令牌权限不足缺少file_read。br3. 环境变量未正确传递。 | 1. 在Figma设置中重新生成令牌。br2. 确认令牌创建时勾选了 file_read 权限。br3. 检查Server启动命令中的env配置或确保本地.env文件已加载。 | | 调用 get_figma_files 成功但返回空列表。 | 1. 提供的 teamId 或 projectId 错误。br2. 该令牌无法访问指定的团队或项目。 | 1. 再次从Figma URL核对ID。br2. 确保生成该令牌的账号是目标团队/项目的成员。 | | 获取的节点JSON数据不完整或缺少属性。 | 1. Figma API调用时未指定需要的参数。br2. 文件过大API返回被截断。 | 1. 查看Figma API文档在 getFileNodes 方法中添加所需查询参数如 ?geometrypaths 获取路径数据。br2. 对于大文件考虑分节点node ids查询或增加请求超时时间。 | | Server启动失败报错 Cannot find package ...。 | 项目依赖未安装。 | 在项目根目录运行 npm install。 | | Node.js 报语法错误如 import 报错。 | package.json 中未设置 type: module或Node版本过低。 | 1. 确认 package.json 包含 type: module。br2. 运行 node -v 检查版本确保是Node 18。 | ## 8. 最佳实践与工程建议 将Figma MCP Server投入生产或团队协作环境时需要考虑以下几点 ### 8.1 安全性增强 * **令牌管理**绝对不要将令牌硬编码在代码或提交到版本库。使用环境变量或安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault。 * **权限最小化**为MCP Server创建专用的Figma账号并生成令牌仅授予其完成工作所必需的 file_read 权限避免使用高权限的主账号令牌。 * **访问控制**可以在MCP Server层增加简单的认证逻辑如允许列表只响应来自受信任客户端如特定IP或带有密钥的请求的调用。 ### 8.2 性能与稳定性 * **缓存策略**Figma设计文件不会频繁变动。可以在Server端对 getFileNodes 的结果进行缓存例如使用内存缓存如node-cache或Redis设置合理的TTL如5分钟避免对Figma API的频繁请求提升响应速度并遵守API速率限制。 * **错误处理与重试**在 figma-client.js 中增加更健壮的错误处理和指数退避重试机制应对网络波动或Figma API临时不可用。 * **分页与增量获取**对于节点数量巨大的文件一次性获取所有数据可能超时或超限。可以改造Tool支持分页或按节点ID范围查询。 ### 8.3 功能扩展 * **更多Tools**根据团队需求暴露更多Figma API能力。 * get_component_sets: 获取所有组件集。 * get_file_styles: 获取文件中定义的样式颜色、文本、效果。 * get_image_fills: 获取图片资源链接。 * **数据预处理与格式化**直接返回原始Figma JSON对AI来说信息量可能过大。可以在Server端进行预处理提取AI更关心的关键信息如组件关系、样式变量、布局约束并格式化为更简洁的结构返回提高AI处理效率和准确性。 * **支持更多AI客户端**除了Claude Desktop可以研究如何配置到Cursor、Windsurf等其他支持MCP的IDE或工具中。 ### 8.4 部署与协作 * **打包与分发**可以将Server打包成Docker镜像方便在不同环境中部署。 * **团队共享**将配置好的MCP Server和Claude Desktop配置文档化让团队其他成员也能一键接入统一设计数据源。 通过本文的实战你已经成功搭建了一座连接Figma设计世界与AI智能体的桥梁。这套方案不仅限于自动生成代码更打开了思路你可以让AI评审设计一致性、计算设计系统覆盖率、甚至基于设计数据生成产品需求文档。