最近在设计稿转前端的过程中，团队遇到一个反复出现的尴尬局面：AI 编程工具能写代码，但它看不懂设计稿的图层结构，只能依赖开发者手动截图、标注、测量间距和颜色。整个流程一旦涉及多页面、多组件，效率损耗非常明显。后来接触到 MCP 服务器这个概念，又围绕 Figma 设计了一版专用的 MCP 服务器，把“设计源文件”直接变成 AI 可以查询和理解的上下文。这篇文章就是想把这个从 0 到 1 的实战过程完整复盘一遍，尤其是“边飞边造引擎”这个状态下，如何做架构取舍、最小实现和灰度切换。
先说结论：Figma MCP 服务器真正解决的，不是“让 AI 打开 Figma”这种表层需求，而是打通了 AI 编程工具与设计源文件之间的上下文断层。它让 AI 能按需读取画布节点、组件属性和样式 token，而不是盯着截图猜参数。这个能力对 AI Engineer 来说，意味着设计交付流程的协作范式发生了变化：设计稿不再只是给人看的，它成了 AI 可以直接访问的数据源。
这篇文章会从问题背景、MCP 原理、Figma API 边界、最小实现、运行验证、踩坑复盘、最佳实践几个角度展开。如果你正在纠结“要不要给团队自建一个 MCP 服务器”，或者“Figma MCP 到底能做什么、不能做什么”，这篇文章应该能帮你省下不少调研时间。
1. 这个问题为什么值得现在解决
很多 AI 编程工具落地时的第一道坎，不是模型能力不够，而是上下文拿不到。尤其是前端开发，设计稿是最高优先级的需求来源，但 AI 拿到手的往往是一张截图、一段描述，或者开发自己转述的“大概样式”。这种信息损耗会导致 AI 生成的代码只能做到“看着像”，距离“设计还原”还差得远。
传统流程里，开发者要从设计稿里人工提取的信息包括：布局结构、间距、颜色、字体、圆角、阴影、组件状态等。一个稍微复杂一点的页面，这些参数可能有几十个。靠肉眼从 Figma 画布上逐个读取，再手动填进代码或者提示词里，既慢又容易出错。
MCP 服务器出现后，这个流程有了新的解法。AI 客户端可以通过 MCP 协议直接向 Figma API 发起查询，按文件、按节点、按组件库粒度获取结构化数据。AI 拿到的不再是“一张图的模糊印象”，而是x、y、width、height、fill、fontSize这些精确值。
从投入产出来看，这个方案特别适合以下三类团队：
- 设计系统成熟、组件库规范、样式 token 统一的团队。MCP 服务器能把设计规范直接暴露给 AI，减少人工解释。
- 前端与设计协作频繁、设计评审多的团队。AI 可以快速基于最新设计稿生成初版代码，降低开发者的重复劳动。
- 正在构建内部 AI 工具链的团队。MCP 服务器是基础设施层的一部分，不是一次性脚本，值得投资。
当然，也不是所有场景都需要自建。Figma 官方已经提供了现成的 Figma MCP 服务器，社区里也有 open-figma-mcp、Figma Context MCP 这类开源实现。如果你只是想快速体验，直接用现成方案更省事。自建的价值在于可控性和扩展性，这个后面会详细展开。
2. MCP 到底解决了什么问题
MCP 的全称是 Model Context Protocol，模型上下文协议。它的目标是让 AI 应用以统一的方式连接外部工具和数据源。类比一下，MCP 之于 AI 工具链，有点像 USB-C 之于外设接口：以前每个外设都要专属线缆，现在大家用同一个标准接口。
在 MCP 的架构里，核心角色有三个：
- MCP 客户端：运行在 AI 应用内部，负责与模型交互，并调用外部工具。
- MCP 服务器：一个独立的本地或远程进程，暴露工具、资源和提示词能力。
- 数据源：Figma、数据库、文件系统、内部 API 等。
当 AI 需要读取 Figma 文件结构时，它不会自己直接调 Figma API，而是通过 MCP 客户端把请求发给 MCP 服务器，由服务器完成 API 调用、数据处理，再以标准格式返回给 AI。这个设计让 AI 应用不需要为每个数据源单独写集成逻辑，也让数据源的所有者可以统一控制权限和返回内容。
理解这个架构，关键在于理解“上下文”这个词。AI 模型本身没有实时获取外部数据的能力，它只能基于对话上下文生成回答。MCP 服务器的作用，就是把外部世界的实时状态变成模型可用的上下文。举个具体例子：如果你直接问一个没有接入任何工具的 AI“这个 Figma 文件的第一屏是什么颜色”，它无能为力。但如果你给了它一个 figma_mcp 工具，它会主动调用工具读取节点信息，然后基于返回数据回答你的问题。
与直接调用 Figma API 相比，MCP 方式有几个差异点：
| 对比维度 | 直接写脚本调 Figma API | 通过 MCP 服务器调用 |
|---|---|---|
| 接入方式 | 每次都要写认证、请求、解析代码 | 客户端配置一次，之后对话式调用 |
| 交互模式 | 开发者手动触发脚本 | AI 根据任务自主决定何时调用 |
| 上下文集成 | 结果打印到终端，需人肉复制 | 结果直接注入模型上下文 |
| 权限控制 | 分散在各脚本中 | 统一在 MCP 服务器层管理 |
| 可复用性 | 单机脚本，难复用 | 一次开发，多个客户端可用 |
当然，MCP 并不是银弹。如果你的需求只是“每天同步一次 Figma 数据到某个系统”，那写个定时脚本可能更直接。MCP 的核心场景是“需要 AI 在对话过程中动态、多轮地获取外部信息”。理解了这一点，你就知道该不该上 MCP 了。
3. Figma MCP 服务器的核心设计与边界
“边飞边造引擎”这个说法，来自一个真实的工程处境：团队已经在用 AI 辅助前端开发了，流程不能停；但现有的方式（截图 + 手动标注）明显撑不住更大的项目，必须把“引擎”升级掉。所谓引擎，就是为 AI 提供设计上下文的这一层能力。
这种状态下的设计原则，和从零开始做新系统完全不同。核心约束有三个：
第一，不能推翻现有工作流。开发者已经习惯“先把设计稿截图发给 AI”这个动作，新方案必须兼容这个习惯，而不是让它变得更复杂。所以 MCP 服务器的工具设计，要尽量覆盖“截图”能表达的信息，但提供更精确的结构化数据。
第二，最小可用优先。第一版不需要把所有 Figma 能力都做成 MCP 工具。先做三个高频操作：读取文件基本信息、按节点查询指定图层数据、导出节点图片。这三个工具能覆盖“AI 理解设计稿 -> 生成代码 -> 对照截图修改”的主链路。
第三，边界要清晰。MCP 服务器是只读层，默认不提供写操作。Figma 文件是企业资产，让 AI 拥有修改设计稿的权限，风险和收益不成正比。写入能力可以等流程跑通后再评估，一开始就收窄权限。
基于这些约束，第一版 Figma MCP 服务器的功能边界可以这样定义：
| 能力模块 | 是否纳入首版 | 说明 |
|---|---|---|
| 读取文件基本信息 | 是 | 获取文件名称、版本、页面列表 |
| 查询节点属性 | 是 | 按节点 ID 获取位置、尺寸、颜色、字体等 |
| 导出节点为图片 | 是 | 生成指定节点的 PNG/SVG 预览 |
| 查询本地样式 | 后续迭代 | 从样式库读取颜色、文字样式 token |
| 修改设计稿 | 否 | 权限风险高，暂不支持 |
| 评论读取/写入 | 否 | 与前端生成主链路无关 |
这个边界设计背后的逻辑是：第一版要解决的是“AI 看不懂设计稿”的问题，而不是“AI 代替设计师操作 Figma”的问题。功能边界越清晰，后续排错和扩展就越容易。
4. 环境准备与前置条件
在写代码之前，需要先确认环境依赖。以下版本要求以官方文档为准，本文示例基于通用思路展开，你本地的具体版本可能略有差异。
4.1 运行环境
- Node.js 18 或更高版本（MCP TypeScript SDK 依赖较新的运行时）
- npm 或 pnpm 作为包管理器
- 一个支持 MCP 客户端的 AI 工具（Claude Desktop、Cline、Cherry Studio 等均可）
- 一个 Figma 账号，且有权限访问你要读取的设计文件
4.2 获取 Figma 个人访问令牌
Figma MCP 服务器的核心凭证是 Personal Access Token（个人访问令牌）。获取路径如下：
- 登录 Figma 网页版。
- 点击右上角头像，进入 Settings。
- 选择 Security 选项卡。
- 在 Personal access tokens 区域，点击 Generate new token。
- 复制生成的令牌，妥善保存。
需要注意，令牌等同于你在 Figma 账号下的操作凭证。它默认拥有该账号能访问的所有文件的读取权限。不要把它提交到 Git 仓库，也不要写在前端代码里。推荐使用环境变量或独立的配置文件管理。
4.3 获取 Figma 文件的 File Key
Figma 文件的 URL 格式通常是：
https://www.figma.com/design/xxxxxxxxxxxx/FileName其中xxxxxxxxxxxx就是 File Key。调用 Figma API 时，需要把它作为路径参数传入。例如：
GET https://api.figma.com/v1/files/xxxxxxxxxxxx如果不知道 File Key 是什么，打开任意一个 Figma 设计文件，看浏览器地址栏即可。
5. 最小可用版本实现
接下来进入代码部分。这里展示的是一个最小可用的 Figma MCP 服务器实现，目标是一个小时内跑通主流程。
5.1 项目初始化
mkdir figma-mcp-server cd figma-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx需要说明的是，@modelcontextprotocol/sdk是 MCP 官方 TypeScript SDK，zod用来做工具参数校验。如果你使用 Python，也可以选择mcpPython SDK，思路一致。
5.2 接入 Figma API 的请求层
创建src/figma.ts，封装 Figma API 调用逻辑：
// 文件路径：src/figma.ts const FIGMA_API_BASE = "https://api.figma.com/v1"; export interface FigmaClientConfig { accessToken: string; } export class FigmaClient { private accessToken: string; constructor(config: FigmaClientConfig) { this.accessToken = config.accessToken; } private async request<T>(path: string): Promise<T> { const response = await fetch(`${FIGMA_API_BASE}${path}`, { headers: { "X-Figma-Token": this.accessToken, }, }); if (!response.ok) { const errorText = await response.text(); throw new Error( `Figma API 请求失败: ${response.status} ${response.statusText} - ${errorText}` ); } return response.json() as Promise<T>; } // 获取文件基本信息 async getFile(fileKey: string) { const data = await this.request<any>(`/files/${fileKey}`); return { name: data.name, lastModified: data.lastModified, thumbnailUrl: data.thumbnailUrl, document: data.document, }; } // 获取指定节点的详细信息 async getNode(fileKey: string, nodeId: string) { const encodedNodeId = encodeURIComponent(nodeId); const data = await this.request<any>( `/files/${fileKey}/nodes?ids=${encodedNodeId}` ); return data.nodes?.[nodeId] || null; } // 导出节点为图片 async getNodeImage(fileKey: string, nodeId: string, format: string = "png") { const encodedNodeId = encodeURIComponent(nodeId); const data = await this.request<any>( `/images/${fileKey}?ids=${encodedNodeId}&format=${format}` ); return data.images?.[nodeId] || null; } }这个请求层做了三件事：统一携带 Figma Token、处理错误状态码、返回 JSON 数据。实际使用中，你可能还需要处理分页、超时等边界情况，但第一版够用了。
5.3 注册 MCP 工具
创建src/index.ts，注册 MCP 服务器与工具：
// 文件路径：src/index.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; import { FigmaClient } from "./figma.js"; const accessToken = process.env.FIGMA_API_TOKEN; if (!accessToken) { console.error("缺少环境变量 FIGMA_API_TOKEN"); process.exit(1); } const figma = new FigmaClient({ accessToken }); const server = new McpServer({ name: "figma-mcp-server", version: "0.1.0", }); // 工具1：读取文件基本信息 server.tool( "get_figma_file_info", "获取 Figma 文件的基本信息，包括文件名、修改时间和页面结构", { fileKey: z.string().describe("Figma 文件的 File Key"), }, async ({ fileKey }) => { const info = await figma.getFile(fileKey); return { content: [ { type: "text", text: JSON.stringify(info, null, 2), }, ], }; } ); // 工具2：按节点查询设计信息 server.tool( "get_figma_node", "获取 Figma 文件中指定节点的详细属性，包括位置、尺寸、填充颜色、字体等", { fileKey: z.string().describe("Figma 文件的 File Key"), nodeId: z.string().describe("Figma 节点 ID，形如 123:456"), }, async ({ fileKey, nodeId }) => { const node = await figma.getNode(fileKey, nodeId); return { content: [ { type: "text", text: JSON.stringify(node, null, 2), }, ], }; } ); // 工具3：导出节点图片 server.tool( "get_figma_node_image", "获取 Figma 指定节点的图片导出 URL，可用于生成设计稿预览", { fileKey: z.string().describe("Figma 文件的 File Key"), nodeId: z.string().describe("Figma 节点 ID，形如 123:456"), format: z .enum(["png", "svg", "jpeg"]) .default("png") .describe("导出图片格式"), }, async ({ fileKey, nodeId, format }) => { const imageUrl = await figma.getNodeImage(fileKey, nodeId, format); return { content: [ { type: "text", text: JSON.stringify({ imageUrl }, null, 2), }, ], }; } ); async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Figma MCP 服务器已启动"); } main().catch((error) => { console.error("启动失败:", error); process.exit(1); });这段代码有三个关键点需要理解：
第一，每个 MCP 工具由名字、描述、参数定义和处理函数组成。AI 模型会根据工具描述决定何时调用它，所以描述要写清楚“这个工具能做什么、适合什么场景”，不要笼统写“获取 Figma 数据”。
第二，返回格式必须是{ content: [{ type: "text", text: "..." }] }。MCP 协议规定工具返回的内容必须是标准化结构，AI 客户端拿到后才会正确解析。
第三，StdioServerTransport表示服务器通过标准输入输出与客户端通信。这种模式适合本地部署，配置简单，不暴露网络端口。
5.4 编译与运行
在package.json中添加脚本：
{ "scripts": { "dev": "tsx src/index.ts", "build": "tsc", "start": "node dist/index.js" } }先以开发模式启动测试：
export FIGMA_API_TOKEN=你的_token npm run dev如果看到Figma MCP 服务器已启动，说明服务器进程正常。
5.5 MCP 客户端配置
以 Claude Desktop 为例，MCP 服务器需要写入客户端配置文件。不同客户端的配置入口不同，但结构类似：
{ "mcpServers": { "figma": { "command": "node", "args": ["/absolute/path/to/figma-mcp-server/dist/index.js"], "env": { "FIGMA_API_TOKEN": "你的_token" } } } }配置完成后，重启客户端，在对话中输入类似下面的提示词触发调用：
请读取 Figma 文件 xxxxxxxx 的页面结构，并说明包含哪些页面。如果配置正确，AI 会主动调用get_figma_file_info工具，并基于返回结果继续对话。如果 AI 没有调用工具，可以更直接地提示：
使用 get_figma_file_info 工具查看文件 xxxxxxxx 的信息。6. 运行验证与效果确认
很多同学第一次跑通 MCP 后，不知道如何确认服务器工作正常。这里提供一个标准验证路径。
第一步，确认服务器进程启动。终端应输出：
Figma MCP 服务器已启动第二步，查看客户端日志。Claude Desktop 的 MCP 日志通常位于：
~/Library/Logs/Claude/mcp*.log日志中如果出现figma相关的连接成功记录，说明客户端与服务器之间的 stdio 通道已建立。
第三步，在对话中触发一次工具调用。请求 AI 获取文件基本信息，然后检查返回内容是否包含文件名称和页面列表。这一步能同时验证三件事：Token 是否有效、File Key 是否正确、工具返回结构是否被客户端正确解析。
如果调用失败，先按下面的顺序排查：
- 看返回的错误信息是
401还是404。401 说明 Token 无效或无权限；404 说明 File Key 错误或文件不存在。 - 看终端是否有异常堆栈。MCP 服务器进程的错误会直接打印在启动它的终端里。
- 看客户端日志中的 JSON 输出。有时工具被调用了，但返回内容过长，客户端截断了展示，这不代表服务器出错。
7. 踩坑复盘：边飞边造引擎的五个教训
复盘整个开发过程，真正有价值的不是代码本身，而是几个容易忽略的工程判断。这里把这五个教训写下来，每个都对应实际场景。
教训一：不要一上来就做“完整版”。第一版只做了三个工具，但我最初设计时列了十个功能，包括样式查询、组件库扫描、评论同步等。后来砍到三个。原因很简单：功能越多，AI 选错工具的概率越大。MCP 工具不是传统 API，每个工具都会被模型当作“决策候选项”。工具数量太少覆盖不了场景，太多则干扰模型判断。
教训二：工具描述比实现更重要。同一个功能，描述写成“获取节点数据”和写成“获取选中节点的布局信息，包括位置、尺寸、填充颜色与字体，用于前端还原设计稿”的调用率差异巨大。模型需要从描述里判断“这个工具适不适合当前任务”，描述越贴近真实任务场景，调用准确率越高。
教训三：错误返回必须结构化。最早版本里，Figma API 报错时直接抛异常，MCP 客户端只能看到一段模糊的堆栈提示。后来改成在工具内部捕获错误，并返回结构化的错误信息：
try { const node = await figma.getNode(fileKey, nodeId); return { content: [{ type: "text", text: JSON.stringify(node) }], }; } catch (error) { return { content: [ { type: "text", text: `查询失败: ${(error as Error).message}`, }, ], }; }这样 AI 拿到错误信息后能自主调整参数重试，而不是直接把对话断掉。
教训四：Figma 文件可能非常大。直接调用/v1/files/{fileKey}拉取整个文件，几 MB 到几十 MB 都很常见。把全量数据塞给 AI 会让上下文爆炸。正确做法是优先使用节点查询接口，只拉取需要的子树。这也意味着，MCP 服务器的工具设计要把“按需查询”作为首要原则。
教训五：切换要灰度，不能一刀切。即使 MCP 服务器开发完成，也不要立刻让团队全部切到新流程。可以先找两三个愿意尝试的开发者，用 MCP 方案做几个小任务，对比输出质量后，再逐步推广。引擎在飞行的过程中更换，靠的不是勇气，而是可回滚的切换机制。
8. 常见问题与排查方法
结合实际落地过程中容易碰到的问题，整理了一张排查表：
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 客户端提示找不到 MCP 服务器 | command路径配置错误，或 Node 不在客户端可访问的 PATH 中 | 检查配置中的绝对路径，直接在终端手动执行命令验证 | 使用which node获取 Node 绝对路径，写入配置 |
| 工具调用返回 401 | Figma 个人访问令牌无效或已过期 | 在终端用 curl 测试 Figma API | 重新生成 Token，更新环境变量 |
| 工具调用返回 404 | File Key 错误，或当前账号无访问权限 | 确认 Figma 文件 URL 中的 Key 和账号权限 | 使用有权限的账号生成 Token，或申请文件访问权限 |
| 对话中 AI 不调用工具 | 工具描述不够具体，或提示词没有触发工具使用意图 | 检查工具描述是否包含任务场景关键词 | 明确提示 AI 使用指定工具，优化工具描述 |
| 返回数据过大，AI 回答卡顿 | 拉取了整个文件结构，上下文占用过高 | 查看返回 JSON 大小，确认是否全量返回 | 改用节点查询，限制层级深度，必要时对返回内容做摘要 |
| MCP 服务器启动后立即退出 | 缺少环境变量 FIGMA_API_TOKEN | 查看启动终端输出 | 设置环境变量后再启动 |
| 多个 MCP 客户端同时使用冲突 | 服务器使用 stdio 模式，无法被多个进程共享 | 观察客户端日志中的连接记录 | 每个客户端配置独立的服务器进程，或改用 streamable HTTP 模式 |
这些问题的共同点是：MCP 服务器本身逻辑并不复杂，复杂度主要来自环境配置和权限管理。排查时优先确认“进程是否能启动”、“API 是否通”、“客户端是否连上”，按这个顺序缩小范围。
9. 最佳实践与工程建议
如果把 Figma MCP 服务器从玩具级别推向生产级别，有几个工程问题值得注意。
9.1 安全与权限
个人访问令牌是最高级别的凭证。它不会过期，一旦泄露，等同于把 Figma 文件暴露给外部。推荐做法是：
- 通过环境变量注入 Token，不写入任何配置文件。
- 对 MCP 服务器所在机器做好访问控制，避免未授权用户读取环境变量。
- 如果团队文件较多，优先考虑使用 Figma 的 OAuth 流程获取受限令牌，而不是统一用一个人的个人令牌。
- 工具权限遵循最小够用原则：只读工具默认开放，写操作一律不加。
9.2 日志与可观测性
MCP 服务器运行在本地 stdio 进程中，出问题时很难远程排查。建议在关键路径加上结构化日志，输出到独立文件：
function log(level: string, message: string, meta?: Record<string, unknown>) { console.error( JSON.stringify({ timestamp: new Date().toISOString(), level, message, ...meta, }) ); }注意这里用了console.error，不要用console.log。因为 stdio 通道的 stdout 被 MCP 协议占用，往 stdout 打印内容会污染协议通信。
9.3 缓存与限流
同一个设计稿在一天的开发过程中会被 AI 反复查询。如果每个查询都实时发到 Figma API，既慢又容易被限流。建议在 MCP 服务器内部加一层简单的内存缓存，按fileKey + nodeId作为 key，设置 5 到 10 分钟的过期时间。对于频繁访问的样式 token，可以预热缓存。
Figma API 有速率限制，具体限制数值以官方文档为准。在实现上要避免 AI 工具并行发起大量请求，可以在工具函数内部加入简单的并发控制。
9.4 版本兼容
MCP SDK 目前迭代较快，不同版本的 API 可能会有破坏性变更。建议在项目里锁定 SDK 的具体版本，定期评估升级。同时，MCP 客户端对工具返回内容的大小也有限制，过长的返回会导致上下文被截断。工具设计时要考虑对 LaTeX、SVG 等大体积数据做摘要或分段返回。
9.5 团队协作流程
MCP 服务器不是一个独立工具，它嵌入在团队的工作流中。建议在项目仓库中维护README文档，写清楚：
- Figma 文件的命名规则和 File Key 获取方式。
- 每个 MCP 工具的作用、参数和典型使用场景。
- Token 的申请流程和保管规范。
- 新增工具时需要遵循的代码规范。
实践下来，文档的价值不亚于代码本身。因为团队成员的 AI 客户端配置各不相同，没有文档，新成员接入成本会很高。
10. 总结与后续学习方向
这篇文章从“AI 看不懂设计稿”这个痛点出发，完整梳理了 Figma MCP 服务器的设计思路、最小实现和落地建议。核心观点可以浓缩成三句话：MCP 的价值在于把外部数据源变成 AI 的上下文；Figma MCP 服务器的首版目标是只读的结构化查询，而不是全量复制 Figma 能力；“边飞边造引擎”的关键不是重写，而是兼容旧流程、灰度切换、可回滚。
如果你准备在自己的项目中实践，建议从最小工具集开始：文件信息、节点查询、图片导出。先跑通一个任务闭环，再用真实反馈迭代工具设计和描述。MCP 本身还处于快速演进阶段，Resources、Prompts 等能力也在逐步完善。后续值得关注的方向包括：本地样式 token 的结构化读取、组件库与代码组件的映射关系、以及 MCP 服务器与前端生成工作流（如 Cursor、Cline 等工具）的更深度集成。
设计稿到代码的距离，本质上就是信息保真度的距离。让 AI 直接读取设计源文件，是缩短这段距离最直接的方式之一。如果你也在做类似的工具，欢迎收藏这篇文章，按里面最小实现的思路先跑通一个版本，再逐步打磨。
