Figma 设计稿和 AI 工具链之间有一条绕不过去的断桥Figma 里的数据是结构化 JSON但大多数 AI 助手的输入只有文本、代码和图片。设计交付时要么人工截图、要么手动复制 JSON、要么写一次性的导出脚本。这次我们来看一个把这座桥直接架起来的实战项目Figma MCP 服务器。它用 MCPModel Context Protocol协议把 Figma 的文件数据、节点结构、图片资源和样式信息暴露给 Claude Desktop、Claude Code、Cursor 这类支持 MCP 的 AI 客户端让 AI 能直接理解设计稿并参与后续开发工作。这篇文章不是工具评测而是一次完整的工程复盘。我会把 Figma MCP 服务器的诞生过程拆开讲从最初“想让 AI 拿到设计稿原生数据”的需求到第一个能跑通的最小原型再到把服务器改造成可维护、可扩展的 MCP 工具集。整个过程很符合标题里的“边飞边造引擎”——先让飞机飞起来再造发动机。文章会覆盖核心能力速览、技术选型、环境准备、服务端实现、工具定义、调试方法、客户端接入、批量场景、踩坑排查和安全边界所有代码都以可复制的命令和配置给出。如果你正在做 AI 工具集成、MCP Server 开发或者想让 AI 直接消费设计稿数据这篇文章可以直接收藏。不需要背景铺垫下面直接进正题。1. Figma MCP 服务器核心能力速览能力项说明项目类型MCP Server连接 Figma 设计数据与 AI 客户端核心协议MCPModel Context Protocol基于 JSON-RPC主要技术栈Node.js / TypeScript官方 MCP SDK数据来源Figma REST API需要 Figma Access Token标准运行方式stdio 模式配置到支持 MCP 的桌面客户端或 CLI扩展运行方式SSE / HTTP 模式可部署为远程 MCP 服务核心工具方向读取文件信息、读取节点结构、导出图片、查询组件与样式、生成结构化摘要是否支持批量任务支持通过遍历节点或批量 ids 参数实现需注意接口耗时是否提供 HTTP APIMCP 本身可走 SSE/HTTP transport等价于接口服务适合场景AI 编程时读取设计稿、设计走查、自动生成代码前的数据准备、设计数据分析和归档需要先明确一点Figma MCP 服务器本身不生成设计稿也不代替 Figma 的编辑能力。它的职责是“把设计数据以 AI 能理解的方式暴露出去”。是否好用取决于工具集的设计、数据裁剪策略和错误处理是否够扎实。2. 为什么需要这个服务器设计稿和 AI 之间的数据断点Figma 文件对 AI 来说并不友好。打开 Figma 的 REST API 返回一个巨大的 JSON 树里面包含 node 的 id、name、type、props、children 等完整描述。这样一个原始文件 JSON 动辄几 MB直接塞给大语言模型的上下文窗口不可能。人工处理也存在问题。前端接到设计稿后常规流程是看标注、量间距、导出切图然后手工写布局代码。这一套流程对 AI 编程工具来说效率太低。如果能给 AI 一套“读取 Figma 文件、抓取某个节点、导出画板图片、拿组件信息”的标准工具AI 就能把设计稿数据直接变成编码依据。这正是 Figma MCP 服务器要解决的问题。用 MCP 协议把 Figma 的能力封装成一组 AI 可调用的工具AI 客户端不再需要关心 HTTP 请求细节、鉴权方式和 JSON 裁剪逻辑它只需要知道“有一个工具叫 get_figma_node传一个文件 key 和节点 id就能拿到这个节点的结构化数据”。从技术演进角度看这也是 MCP 生态的典型应用场景。MCP 的核心价值不是提供一个新 API而是让工具以统一方式接入 AI 工作流。对于 Figma 这种几乎天天要用的协作设计工具把它接入 MCP 生态之后AI 编程、文档生成、设计走查都能共用一套数据接口。3. 总体架构设计先用起来再造引擎这个项目最值得复盘的一点就是开发节奏。项目需求非常明确但边界不清楚AI 到底需要 Figma 的哪些数据是只要节点树还是要图片、样式、组件引用如果一开始就把所有功能设计完再动手项目可能两周都上不了线。实际执行分成了两阶段。第一个阶段叫“先飞”只实现三个最小工具文件信息、节点查询、图片导出。工具返回原始 JSON不做任何裁剪。这个版本很粗糙但有价值因为团队立刻能在 Claude Desktop 里调用它验证 AI 拿到设计数据后能不能干活。第二个阶段叫“再造引擎”根据使用过程中的真实反馈重构 MCP Server 的架构。主要做了三件事之后让 Claude 用一段文本描述生成的 web 应用含文件树和代码同时剪裁原始 JSON 成结构化摘要增加缓存层避免重复读取同一个大文件把 Figma API 请求和 MCP 工具定义分离后续加工具不需要修改既有调用逻辑。架构上项目分成四层分层职责MCP 工具层定义工具名称、输入参数、输出内容Figma 服务层封装 Figma REST 请求、鉴权、错误处理数据裁剪层将 Figma JSON 转为摘要、列表、过滤文本传输层配置 MCP 的 stdio 或 SSE transport这种分层的好处是工具层只关心“这个工具叫啥、参数怎么校验”实际数据获取完全交给 Figma 服务层。数据裁剪层单独存在是为了让 AI 拿到的内容大小可控。如果以后要支持其他设计工具只需要替换 Figma 服务层MCP 工具层基本不用动。4. 环境准备与前置条件开发这个服务器不需要特别高的硬件门槛一台普通开发机就行。如果只跑本地 stdio 模式资源消耗甚至比一个 Node 服务还低。关键前置条件如下操作系统Windows、macOS、Linux 都可以推荐在开发机装 Node.js。Node.js建议 18 LTS 以上MCP SDK 和相关依赖需要较新的 Node API。包管理器npm 或 pnpm 均可。Figma 账号和 Access Token在 Figma 个人设置里生成用于调用 REST API。MCP 客户端Claude Desktop、Claude Code、Cursor、或者官方 MCP Inspector 任选一个用于调试。Figma 文件地址需要拿到 Figma 文件的 file key这个值在文件 URL 里的 /file/ 之后。node -v npm -v安装 MCP SDK 和相关依赖npm init -y npm install modelcontextprotocol/sdk zod npm install -D typescript tsx types/node由于 MCP SDK 的包版本迭代比较快不同小节里的 import 路径可能有差异。较新版本推荐从modelcontextprotocol/sdk/server/mcp.js导入McpServer如果遇到旧版示例Server从modelcontextprotocol/sdk/server/index.js导入。安装后以实际版本为准。{ scripts: { dev: tsx src/index.ts, build: tsc, start: node dist/index.js } }生成 Figma Access Token 的路径是Figma 头像菜单 - Settings - Security - Personal access tokens - Generate new token。注意Figma 个人访问令牌只显示一次生成后立刻保存。如果丢失只能重新生成。实际开发中建议把 token 放在环境变量里不要写进代码和配置文件。export FIGMA_ACCESS_TOKEN你的_token export FIGMA_FILE_KEY你的_file_key5. 服务端核心实现与工具集设计先启动服务。下面是一个最小可用的 MCP Server 骨架后续所有工具都注册在这个 server 实例上。import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new McpServer({ name: figma-mcp-server, version: 0.1.0 }); await server.connect(new StdioServerTransport());这个骨架通过标准输入输出和 MCP 客户端通信。MCP 客户端发现工具、调用工具、接收结果全部走 JSON-RPC 消息。5.1 工具一读取 Figma 文件信息第一个工具解决最基本的问题AI 先知道整个文件里有什么。Figma 文件的原始 JSON 很大直接返回会浪费大量 token所以这里要做一个“文件摘要”逻辑。import { z } from zod; server.tool( get_figma_file, 获取 Figma 文件的基本信息、页面列表和节点摘要, { fileKey: z.string().describe(Figma 文件 key) }, async ({ fileKey }) { const fileData await fetchFigmaFile(fileKey); const summary summarizeFile(fileData); return { content: [{ type: text, text: JSON.stringify(summary, null, 2) }] }; } );summarizeFile的核心操作是遍历document.children提取每个页面的 id、name、type然后对每个页面递归统计子节点数量最后生成一份轻量级清单。这样 AI 拿到的是“文件里有几个页面、每个页面有哪些画板”而不是几万行 JSON。5.2 工具二按节点 ID 获取设计稿数据文件信息只能给出骨架。当 AI 确定要分析某个页面或画板时需要用节点 ID 精确拉取。这个工具比较实用尤其适合让 AI 读取某个具体界面的结构和文本内容。server.tool( get_figma_node, 获取 Figma 文件中指定节点的数据和属性, { fileKey: z.string(), nodeId: z.string().describe(Figma 节点 id例如 0:1) }, async ({ fileKey, nodeId }) { const nodeData await fetchFigmaNode(fileKey, nodeId); const trimmed trimNodeData(nodeData); return { content: [{ type: text, text: JSON.stringify(trimmed, null, 2) }] }; } );Figma 的 nodes API 支持ids参数可以一次传多个节点用逗号分隔。项目里工具定义支持 nodeId 为单个字符串但服务层内部可以同时支持批量模式。async function fetchFigmaNode(fileKey: string, nodeId: string, depth 2) { const url https://api.figma.com/v1/files/${fileKey}/nodes?ids${encodeURIComponent(nodeId)}; const response await fetch(url, { headers: { X-Figma-Token: process.env.FIGMA_ACCESS_TOKEN ?? } }); // 后续对响应做裁剪 }注意Figma nodes API 返回的 JSON 同样可能很大裁剪策略不能省。比较稳妥的做法是限制递归深度默认取两层到三层文本节点只保留字符数超过 0 的内容样式相关的 painted 信息要有选择地保留。5.3 工具三导出节点为图片设计稿转代码时AI 光看 JSON 结构看不到视觉效果。图片导出工具要解决这个问题。Figma 的 images API 返回的是 HTTPS 图片 URL不是图片二进制。MCP 工具可以直接把 URL 返回给 AI 客户端但更可靠的方式是服务器下载图片并转 base64 后返回。server.tool( export_figma_image, 导出 Figma 节点为 PNG 图片, { fileKey: z.string(), nodeId: z.string(), format: z.enum([png, svg, jpg]).default(png), scale: z.number().min(0.25).max(4).default(1) }, async ({ fileKey, nodeId, format, scale }) { const imageUrl await fetchFigmaImage(fileKey, nodeId, format, scale); const base64 await downloadImageAsBase64(imageUrl); return { content: [ { type: text, text: data:image/${format};base64,${base64} } ] }; } );从实际运行效果看Figma 导出图片 URL 的有效期并不是永久的而且如果文件权限或 token 失效图片请求会直接 403。所以把图片转为 base64 放进 MCP 返回内容可以避免 AI 客户端后续访问 URL 时失败。5.4 工具四查询组件和样式这个工具服务于设计规范一致性需求。Figma 文件里的组件和样式名称是前端开发的重要依据。AI 拿到这些信息后可以自动匹配现有组件库避免从零写代码。server.tool( get_figma_styles, 获取 Figma 文件的颜色、文本和效果样式列表, { fileKey: z.string() }, async ({ fileKey }) { const styles await fetchFigmaStyles(fileKey); return { content: [{ type: text, text: JSON.stringify(styles, null, 2) }] }; } );Figma 的 styles API 返回的样式列表包含 styleId、styleTypeFILL、TEXT、EFFECT 等、name、description 和 key。对 AI 编码上下文来说颜色样式尤其重要直接对应到前端设计 token。5.5 工具五生成可供 AI 阅读的设计分析报告这是第二阶段新增的工具也是“再造引擎”的核心产物。它把前面几个工具的能力组合起来一次性给 AI 一个完整的设计稿结构化描述。server.tool( analyze_figma_canvas, 分析指定画板生成适合 AI 阅读的设计描述, { fileKey: z.string(), nodeId: z.string() }, async ({ fileKey, nodeId }) { const node await fetchFigmaNode(fileKey, nodeId, 3); const image await fetchFigmaImage(fileKey, nodeId, png, 2); const report buildDesignReport(node, image); return { content: [{ type: text, text: report }] }; } );buildDesignReport会输出画板尺寸、背景色、主要文本层级、子节点数组结构、组件引用列表以及一张图片的 base64。这个报告不追求完整还原设计稿而是给 AI 一条清晰的分析路径避免大模型在海量 JSON 里迷失方向。6. 启动、调试与 MCP 客户端接入6.1 本地启动调试开发阶段用 tsx 直接跑 TypeScript 文件最快npm run dev生产构建后再用 Node 跑编译结果npm run build npm start由于 MCP 的 stdio 模式本身不监听端口启动后不会出现类似“访问 127.0.0.1:7860”的提示而是保持进程等待标准输入消息。这个设计容易让第一次接触 MCP 的开发者以为启动失败了实际服务已经就绪。6.2 使用 MCP Inspector 调试官方 MCP Inspector 是调试 MCP Server 最直接的工具。安装并运行npx modelcontextprotocol/inspector node dist/index.js然后在浏览器打开 Inspector 提供的地址就能看到工具列表、参数校验和调用结果。它比直接在客户端里测试更高效因为能够清楚地看到每条 JSON-RPC 请求和响应。调试时重点看三块内容工具列表是否正常展示参数 schema 是否正确。调用某个工具后返回耗时尤其是大文件读取是否超时。错误信息是否完整有没有暴露 token 或内部路径。6.3 配置 Claude Desktop把 Figma MCP 服务器配置到 Claude Desktop需要编辑客户端的 MCP 配置文件。以 macOS 为例配置文件路径一般在~/Library/Application Support/Claude/claude_desktop_config.json。{ mcpServers: { figma: { command: node, args: [/absolute/path/to/figma-mcp-server/dist/index.js], env: { FIGMA_ACCESS_TOKEN: 你的_token } } } }配置完成后重启 Claude Desktop在对话里请求“读取当前设计稿的页面列表”如果能看到工具调用记录说明整条链路已经通了。6.4 MCP 工具的调用效果验证以下是一次标准的 MCP 工具调用与返回流程{ jsonrpc: 2.0, method: tools/call, params: { name: get_figma_node, arguments: { fileKey: abc123, nodeId: 123:456 } } }响应会是一个 content 数组里面包含 type 为 text 的字符串内容。AI 客户端拿到这个字符串后会继续处理成可读回复。如果调用失败响应中会返回 isError 为 true 的结构错误原因可以从调试日志里看。判断一次调用是否成功的标准很简单客户端能根据返回的数据给出有意义的分析结果而不是报“工具错误”或“数据为空”。7. 接口 API 与批量任务场景MCP Server 本身就把能力暴露成工具理论上每个工具都可以作为 AI 工作流里的一个接口单元。对 Figma 场景来说批量需求集中在这几类7.1 批量读取页面节点Figma 的 nodes API 支持一次传入多个节点 ID。在批量场景中可以先调用节点查询工具把所有需要的节点 ID 收集起来再分批拉取数据。async function fetchNodesInBatches(fileKey: string, nodeIds: string[]) { const batchSize 20; const results []; for (let i 0; i nodeIds.length; i batchSize) { const batch nodeIds.slice(i, i batchSize); const data await fetchFigmaNode(fileKey, batch.join(,)); results.push(data); } return results; }批量拉取时要特别小心文件大小。20 个复杂节点可能比一整个页面文件还大所以返回给 AI 之前必须继续裁剪。更好的做法是只提取每个节点里的关键字段不要直接透传完整的 Figma Node JSON。7.2 批量导出画板图片批量导出图片适合“设计走查”或“自动生成界面截图归档”。Figma images API 本身支持一次传很多节点 ID并返回一个以节点 ID 为 key 的图片 URL 字典。服务器侧可以做并发下载限制避免一次性把 Figma 的 API 配额打满。async function exportAllFrames(fileKey: string, frameIds: string[]) { const imageUrlMap await fetchFigmaImages(fileKey, frameIds); const results {}; for (const [id, url] of Object.entries(imageUrlMap)) { results[id] await downloadImageAsBase64(url); } return results; }建议在批量导出前增加一次节点数量校验超过限制就拒绝执行。这样能避免 MCP 工具调用长时间挂起。7.3 结合 AI 工作流批量生成代码Figma MCP 服务器的终极用途不是单独跑一个工具而是把它接入整个 AI 编码流水线。比如让 AI 逐页读取画板对每个画板生成对应的前端组件代码最后汇总成一份页面清单。这个场景下MCP Server 更像是“数据源”AI 客户端负责编排。实际运行中AI 先调用analyze_figma_canvas拿到页面结构和图片再结合项目代码库的上下文生成组件。如果单次调用 token 超限可以把分析报告分段传入。8. 实战中的常见问题与排查方法问题现象可能原因排查方式解决方案401 UnauthorizedFigma Access Token 无效或已过期检查 token 生成时间用 curl 直接请求 Figma API重新生成 token更新环境变量403 Forbiddentoken 没有该文件权限或文件被删除/转移确认 token 权限和文件可见性在 Figma 中共享文件给 token 所有者或更换文件 key404 Not FoundfileKey 或 nodeId 填写错误核对 Figma 文件 URL 中的 key 和节点 id在 Figma 编辑器中打开文件从 URL 复制 key返回内容过大未做数据裁剪或递归深度过深查看 MCP Inspector 的返回 JSON 大小增加层级限制截断文本字段只保留摘要图片导出超时节点过多或图片分辨率过高检查 images API 响应时间和导出 scale 参数降低 scale分批导出增加超时时间MCP 客户端显示工具找不到Server 启动失败或配置路径错误启动后用 MCP Inspector 测试检查命令路径是否绝对路径确认 token 是否注入工具调用成功但 AI 回复质量差返回给 AI 的数据不符合任务要求看工具返回内容确认字段是否为 AI 需要的信息优化裁剪层摘要增加结构化描述内存占用缓慢增长大文件 JSON 反复缓存在内存里观察服务运行时内存曲线增加缓存淘汰策略限制单次返回大小从开发经验看最常出问题的地方不是 MCP 本身而是 Figma API 的复杂性和权限层级。开发时不要只看 MCP 工具调用的报错先单独用 curl 验证 Figma API 是否能正常返回数据可以快速定位问题在哪一层。curl -H X-Figma-Token: $FIGMA_ACCESS_TOKEN \ https://api.figma.com/v1/files/$FIGMA_FILE_KEY如果 curl 能拿到 JSON就说明权限和 key 没问题问题出在 MCP Server 的数据处理环节。9. 资源占用与性能观察Figma MCP 服务器的资源消耗不在推理模型那个量级但依然有观察价值。核心消耗来自两块Figma API 请求的等待时间以及大 JSON 的解析和缓存。运行时观察重点启动后内存占用通常在几十 MB 到几百 MB 之间取决于文件缓存和 token 大小。读取大文件时CPU 峰值主要出现在 JSON.stringify 和递归裁剪过程。图片导出时下载图片并转 base64 会占内存建议设置单张图片大小上限例如 2MB 以内。一台 2 核 4G 的轻量服务器跑远程 SSE 模式完全够用。如果只是为了本地开发和 Claude Desktop 跑在同一台机器上资源压力几乎可以忽略。降低资源占用的几个有效方式// 限制返回给客户端的节点数量 const MAX_NODES 100; // 限制单次请求的递归深度 const MAX_DEPTH 2; // 图片最大尺寸限制 const MAX_IMAGE_BYTES 2 * 1024 * 1024;用简单的 LRU 缓存避免重复读取相同文件const cache new Mapstring, { data: any; time: number }(); const CACHE_TTL 60 * 1000; async function fetchFigmaFileCached(fileKey: string) { if (cache.has(fileKey)) { const hit cache.get(fileKey)!; if (Date.now() - hit.time CACHE_TTL) return hit.data; } const data await fetchFigmaFile(fileKey); cache.set(fileKey, { data, time: Date.now() }); return data; }不要让缓存无限增长。对大文件设置 30 到 60 秒的 TTL 已经足够因为 AI 工作流通常是一次性读取不需要长时间保留旧数据。10. 最佳实践与安全合规10.1 代码层面把 Figma API 请求封装在独立模块禁止在工具注册文件里直接写 fetch URL。所有工具参数都过 zod 校验避免非法输入直接打到 Figma API。输出给 AI 的数据必须先裁剪不要把整段原始 JSON 无脑返回。超时时间要单独配置Figma 大文件接口经常超过默认 10 秒超时。10.2 安全与权限层面绝不把 Figma Access Token 提交到 Git 仓库使用环境变量或密钥管理服务。部署到远程服务器时只对内网或受控网络暴露 SSE/HTTP 端口。不存储 Figma 文件内容到日志里。打印日志时只输出文件 key、节点 id 和返回字节数。涉及设计稿数据时必须先确认文件授权范围。不要用个人 token 读取团队尚未授权的文件。10.3 合规边界Figma 里的设计稿是团队资产和可能受版权保护的作品。用 MCP Server 把这些数据提供给 AI 处理本质上是数据流动。使用前需要确保设计稿属于你自己或你的团队或者你已获得文件所有者的明确授权。处理敏感设计数据时优先使用本地部署的 MCP Server 和本地模型避免把未脱敏的设计稿外发。商用场景生成代码前确认字体、图片素材、组件库的使用许可。11. 项目复盘小结这个 Figma MCP 服务器最大的价值不是提供一个标准 API而是给 AI 工作流打开了一条“理解设计稿”的通道。从最初的三个粗糙工具到现在的文件摘要、节点裁剪、图片导出、组件查询、分析报告组合迭代过程完全围绕实际使用反馈展开。值得先验证的功能是analyze_figma_canvas。拿一个真实的高保真画板测试AI 能根据返回的报告给出相对准确的前端实现思路这是一台能用起来的核心体验。最容易踩的坑还是数据裁剪和超时问题。Figma 文件 JSON 太大不做裁剪会让 AI 客户端直接卡住图片导出节点太多会让 MCP 调用超时。解决好这两个问题整个服务器就稳了。后续可以扩展的方向很多增加写回能力比如给 Figma 节点添加评论或者更新文本内容。支持增量读取只返回文件变更后的节点避免每次全量拉取。对接更多客户端比如 Trae、Cursor 里的 MCP 配置以及蓝湖 MCP 这类设计协同生态。增加远程 SSE transport把 MCP Server 部署成一键启动的独立服务。如果后续做云端部署建议把 Figma 文件 key 和 token 的绑定关系做成多租户配置避免一个 token 读取所有文件带来的越权风险。总之Figma MCP 服务器是一次典型的“AI 工程化”实践先解决最痛的数据接入问题再逐步优化架构和工具集。设计稿是前端开发绕不开的源头把这条数据链路打通AI 工程师后面的路会顺很多。建议直接拿一个现有 Figma 文件试跑整套流程跑通一次你就会明确知道这个服务器该往哪个方向迭代。