先说结论这活儿能做而且做完整了团队的前端产能能明显松一口。我最近在内部搭了一套面向 Figma 设计稿解析的 MCP / Skill 方案从需求调研到选型、从部署到排障前前后后折腾了两周多。很多团队其实都在琢磨同一件事怎么让 AI 编码工具直接看懂设计稿。标题里的“内网可部署”这五个字才是真正的难点所在。今天就把整份分析、方案和实操过程整理出来给同样在做这件事的工程师一点参考。开头先把几个概念对齐一下Figma 是设计协作工具几乎是前端团队绕不开的“设计真相源”MCPModel Context Protocol是 Anthropic 推出的模型上下文协议核心价值是让 AI 能标准化地调用外部工具Skill 在编码 Agent 的语境里更像是一个“专项技能包”把提示词、上下文、工作流和工具调用组合在一起。一套做下来AI 能从 Figma 里读出布局、样式、组件和设计规范再转成可落地的代码结构省掉大量人工量稿和手写样式的时间。1. 为什么“内网可部署”这件事值得单独写一份报告1.1 设计稿到代码的鸿沟是当前 AI 落地中最值得攻的点之一做过前端的人都有感触设计稿转页面技术含量不一定高但耗时绝对不低。拿到一张 Figma 设计稿要画像素、量间距、提取颜色、切图、还原字体……这些重复劳动占掉了开发节奏里很大一块时间。传统做法是用蓝湖、即时设计这类工具做标记和切图但切出来的还是“素材”离“代码”还差一步。AI Agent 真正进入研发流程后“让 AI 直接读设计稿”就从一个锦上添花的想法变成了一条明确的落地路径。以 Claude Code、Cursor 为代表的编码 Agent 擅长理解自然语言和代码但它们默认看不见设计稿里的图层和样式。过去做这类需求要么让人先把设计稿翻译成文字描述要么想别的偏方。现在 MCP 协议的意义就在这里它给了 Agent 一条标准化的“眼睛”让 Agent 能够通过工具接口直接读取 Figma 文件里的结构化数据。这一步打通设计稿到代码的链路才算真正闭环。1.2 内网部署不是“可选”而是很多团队的硬性门槛这可能是整个方案里最容易被低估的部分。Figma 本身是 SaaS 服务所有的文件、节点、样式数据都托管在云端。对于一个普通外包项目或小团队直接让 AI 工具通过公网访问 Figma API 完全够用。但对于中大型企业尤其是金融、能源、政企、通信这些行业数据出域管控是第一优先级。设计稿虽然看起来不如代码敏感但它同样承载了业务逻辑、产品规划、甚至内部系统的界面结构属于典型的知识产权范畴。很多安全审计会明确要求设计数据不得越过内网边界。这就是“内网可部署”的由来我们需要一套部署在企业内网的解析服务让 AI 工具只能访问内网地址而不是直接打公网接口。理想情况下Figma 的设计数据可以被动同步到内网也可以在内网做一层代理和缓存对外完全只暴露内网服务端口。数据链路清晰可控审计有日志可查才不会在安全评审环节被卡住。1.3 MCP 与 Skill两条容易混淆的落地路径MCP 和 Skill 并不是同一个层级的东西很多人一开始会把它们混为一谈。MCP 是协议解决的是“AI 怎么调用外部能力”的管道问题Skill 是技能封装解决的是“AI 拿到能力之后怎么高质量地完成某个专项任务”的编排问题。用一个比喻MCP 是给了机器人一双手Skill 是教会机器人怎么用这双手去做一道菜。实际落地的时候两者不是二选一而是配合使用。团队可以先部署一个 Figma MCP Server把“读取文件节点”“获取样式”“导出图片”这些原子能力暴露给 Agent然后在 Skill 层把“根据设计稿生成前端页面”这一整套工作流封装起来包括读取设计稿、理解布局、抽取样式、生成代码、输出自查报告等一系列步骤。这样一来普通使用者不需要理解 MCP 配置只需要触发 SkillAgent 会自动按流程调用 MCP Server。后文会分别展开两层的设计与实现。2. 技术方案拆解从 Figma 文件到结构化设计数据2.1 Figma 设计稿解析的全链路到底在解析什么先明确一个容易忽略的事实Figma 设计稿本质上是一棵巨大的节点树。一个.fig文件在云端存储时包含画布Canvas、框架Frame、组Group、矢量路径Vector、文本Text、组件Component等多种节点类型。每个节点都带有一堆属性坐标、宽高、填充、边框、圆角、阴影、字体、字号、行高、字重。要解析设计稿目标就是把这一串属性完整地读取出来并且保留层级关系。Figma 官方提供的 REST API是当前最常见的数据来源。核心接口有两个GET /v1/files/:key拿到整个文件的完整节点树GET /v1/files/:key/nodes按节点 ID 批量获取局部数据。前者数据量大文件复杂的场景下可能返回几 MB 甚至几十 MB 的 JSON后者更适合做增量更新比如只读取某个页面的局部信息。除了节点属性还有两个高频接口GET /v1/images/:key用于导出图片或切图资源GET /v1/component/:key用于读取组件信息。解析质量的高低决定了后续 AI 生成代码的上限。举个例子一个按钮的宽度如果是固定 120pxAI 可以原样写入代码但如果你希望 AI 生成自适应布局它就得同时知道按钮的约束Constraints和父级 Frame 的布局模式Auto Layout 的 direction、padding、itemSpacing 等信息。这些细节都在节点属性里解析的时候必须一张一张地提取。实际开发中我建议重点抽取以下字段节点类型、name、boundingBox、layoutMode、primaryAxisAlignItems、counterAxisAlignItems、paddingLeft/Right/Top/Bottom、itemSpacing、fills、strokes、effects、cornerRadius、textStyle、fontName、fontSize、lineHeight、letterSpacing。只要这些字段齐全AI 生成出来的页面在结构还原度上就有保障。2.2 MCP Server 在这条链路里到底扮演什么角色MCP Server 的角色本质上是“把 Figma API 的 REST 能力包装成 Agent 能直接调用的工具”。从 MCP 协议的角度看一个 Server 通常暴露三类能力Tools可执行的工具、Resources可读取的资源、Prompts可复用的提示模板。对于 Figma 解析场景最核心的是 Tools。我设计的 MCP Server 里一共规划了这几个核心 Toolget_file_structure(file_key)获取整个文件的页面与帧结构让 Agent 先建立空间的整体认知类似于人打开设计稿先看有哪些页面。get_node_info(file_key, node_id)获取单个节点的完整属性重点返回布局、样式、文本相关字段供 Agent 按需深入查看。export_node_image(file_key, node_id, format, scale)将节点导出为 PNG 或 SVG 图片Agent 可以把图片附加到对话上下文中进行多模态理解。get_file_styles(file_key)收集文件内的颜色、文本、效果等样式声明相当于自动提取设计规范。get_component_info(file_key, component_id)读取组件信息方便 Agent 在还原设计稿时复用团队已有的设计系统组件。每个 Tool 都必须有清晰的参数描述和返回值格式这一点在 MCP 场景里尤其重要。因为 Agent 是用自然语言来决策调用哪个工具、传什么参数的如果 Tool 描述写得含糊Agent 就很容易传错参数或者跳过工具直接编造答案。我在写 description 字段的时候会刻意写明“此工具返回 JSON包含节点坐标与样式可用于生成 CSS 代码”这样 Agent 在计划阶段就能感知到工具的用途与产出。Resources 层面我建议把“Figma 文件本身”当作资源来暴露比如暴露figma://{file_key}这样的资源 URI让 Agent 可以按需读取文件的关键内容。Prompts 层则可以放一些“从设计稿生成 React 组件”“提取设计 Token”这类高频任务模板。Tools、Resources、Prompts 三者的关系不是互斥的而是从粗到细、从执行到编排逐步深入。2.3 Skill 封装的关键把“拿数据”变成“做任务”MCP Server 做出来的是一堆原子能力但团队里真正用 AI 写页面的人不可能每次都手动吩咐 Agent “先读取文件结构再获取这个节点然后导出图片……”这些都是重复且专业的工作流。Skill 要解决的就是这个上层封装问题。一个前端页面还原类的 Skill设计上至少应该包含五个阶段理解设计稿结构、抽取关键样式信息、形成页面还原方案、生成代码、输出还原说明。在实现上Skill 的核心是一份精心编写的指令模板里面写好每个阶段 Agent 该做什么、调用哪些 MCP 工具、输出什么格式的内容、遵循什么团队的代码规范。举个例子我们的 Skill 指令里会明确要求 Agent 在读取图稿后先输出一份“页面结构分析”把每一个区块的布局方式、尺寸、间距、颜色列出来然后要求它基于 MCP 返回的样式数据生成 Tailwind CSS 类的代码最后还要求它检查一遍生成结果与原始设计稿的差异输出一个自查清单。这样做的好处是输出结果的质量下限被拉高了哪怕使用者只是简单说一句“根据 XXX 页面生成前端代码”Agent 也知道完整流程该怎么走。3. 内网部署的架构设计与实现3.1 三种可行的部署模式如何选型方案设计阶段我对比了三种内网部署模式各有适用场景没有绝对的好坏只有合不合适。模式 A内网 MCP Gateway 直连 Figma 云 API这种模式下MCP Server 部署在内网但它对外访问公网 Figma API。换句话说数据流是Agent → 内网 MCP Server → 公网 Figma API → 返回数据。优点是实现简单不需要做数据同步Figma 上改了设计稿AI 立刻能看到最新版。缺点是数据仍然经过了公网链路只是把“AI 工具直连”换成了“内网服务器代理”。对安全要求极严的团队来讲这条链路在审计时可能会被打回。模式 BFigma 设计数据同步到内网 内网解析服务这种模式下我们单独做一个同步服务定时或通过 Webhook 监听 Figma 文件的变更把节点树、样式、图片等数据拉取下来存储到内网的数据库或文件系统中。解析时 MCP Server 只读内网数据彻底断开了对公网的依赖。优点是数据可控性最强内网任何服务都不会触碰公网安全性最容易被安全团队接受缺点是需要额外维护一套同步机制数据实时性取决于同步频率。模式 C离线设计稿导入设计师把 Figma 文件导出为.fig或通过插件导出为 JSON / 图片 Bundle再上传到内网由解析服务处理。优点是彻底离线适合网络隔离环境或者只在项目启动阶段做一次静态还原的场景。缺点是不能持续追踪设计变更每次要人工导出导入适合临时任务不适合高频迭代的长期项目。三种模式我做了张对比表维度模式 A网关代理模式 B数据同步模式 C离线导入数据实时性强取决于同步频率差需人工操作安全合规性中强最强实施复杂度低中高低维护成本低中低适用场景开发测试环境中大型企业生产环境隔离内网、静态项目大多数正式生产环境我推荐模式 B这是唯一能从数据链路根本上满足内网部署语义的方案。如果现阶段实施周期太紧可以先临时用模式 A 把流程跑通验证设计和开发两端的协作深度再逐步演进到模式 B。3.2 推荐方案Figma API 代理同步 内网数据缓存 MCP Server最终采用的组合是“同步服务 内网数据缓存 MCP Server”三段式架构。同步服务负责从 Figma 拉数据写入 PostgreSQL 或 MongoDB。我建议用 PostgreSQL因为 JSONB 类型可以很自然地存储 Figma 的节点树数据同时还支持按节点 ID 做索引查询。数据量上一个大型文件的节点 JSON 加上图片资源可能在 200MB 到 1GB 之间一张表存节点树一张表存图片二进制配合对象存储完全在可控范围内。同步策略上我设计了全量同步 增量更新两层。全量同步在首次接入时执行比如凌晨低峰时段跑一次。增量更新靠 Figma Webhook 触发Figma 文件发生变更后Webhook 回调内网同步服务同步服务调用GET /v1/files/:key/nodes只把变更的节点拉回来更新内网数据库。这套机制跑起来之后设计稿基本能在改动后几秒到十几秒内反映到内网AI 拿到的几乎接近实时数据。MCP Server 本身只是个 Node 或 Python 服务部署在内网一台 2C4G 的虚机上完全够用因为它不直接跟 Figma API 打交道只读内网数据库和文件存储。这样一来MCP Server 的响应速度也更快了——同样一个get_node_info请求内网数据库本地查询只需几十毫秒远比请求公网 API 快。3.3 权限与安全控制如何做到既好用又合规内网服务最怕的就是“打开门之后没人管了”。Figma 里不同项目、不同页面权限可能完全不同同步服务做数据拉取时用的是一个大的访问 Token但 Token 能看什么内容可能在 Figma 后台只做了粗略的项目级限制。到了内网MCP Server 如果对所有人开放所有文件的读取权限就存在越权风险。我做的权限控制分两层HTTP 请求层的认证与数据层的文件级授权。MCP Server 支持 API Key 认证内网系统接入时必须在 Header 里携带分配好的 Key。数据层方面我在数据库里给文件元数据打上了业务线标签比如“支付中台”“会员中心”每个 API Key 关联一组可访问的业务线标签。Agent 请求某一个文件时Server 先校验 Key 是否有这个文件的访问权限没有就直接拒绝。审计方面MCP Server 会对每次工具调用记录访问日志记录发起方、文件 Key、节点 ID、时间戳和返回状态。这些日志对接到企业内部的日志平台出问题时能追溯到具体某一次调用到底读到了什么。实践证明这个设计在过安全评审时极大地降低了沟通成本审计人员只需要看日志规范就能确认数据流向是可控的。4. 实操从零搭建一套可用的 Figma MCP Server 与 Skill4.1 前置准备Figma Token、内网服务器、MCP 客户端环境动手之前先把需要的东西列全Figma 账号以及一个个人访问令牌Personal Access Token。在 Figma 的 Account Settings → Security 页面可以生成Token 需要勾选File content: Read-only和Comment: Read-only权限即可满足读取设计稿数据的需求。生成后妥善保存它等同于你的账号权限泄露风险很高。一台能访问内网数据存储的运行环境。推荐 Linux 服务器Ubuntu 22.04 或 CentOS 7Node.js 18 和 Python 3.10 二选一或都装上取决于选用哪个语言的 MCP SDK。MCP 客户端。Claude Desktop、Claude Code、Cursor 都支持配置 MCP Server自研 Agent 也可以通过官方 SDK 接入。我实测下来Claude Code 对 MCP 生态的支持最完整Cursor 在 MCP 工具调用上偶尔会出现上下文记忆不完整的问题但这不影响整体方案的成立。内网服务器需要能访问 Figma API如果采用模式 B至少同步服务所在的机器要能访问公网同时客户端机器需要能访问内网 MCP Server 的 HTTP 服务端口。网络规划时一定提前确认这两条线路是通的不然后面排查会浪费很多时间。4.2 部署一个开源的 Figma MCP Server并对接内网数据源当前社区已经有不少开源的 Figma MCP Server 实现比如figma-developer-mcp、Figma Context MCP等。如果你的场景是模式 A可以直接用官方或社区版本配置环境变量FIGMA_API_KEY再指定要暴露的文件 Key 列表就能让 MCP Server 直连 Figma API。但我们的场景是模式 B需要改造成“MCP Server 读内网数据库”而不是直接打公网。改造思路是重写 MCP Server 中的get_file_structure、get_node_info、export_node_image等核心 Tool 的数据源把原来调用 Figma REST API 的代码替换成查询内网 PostgreSQL / 对象存储的代码。这里我以 Node.js 生态和modelcontextprotocol/sdk为例描述核心注册工具的代码结构import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { z } from zod; const server new McpServer({ name: figma-intranet-mcp, version: 1.0.0 }); server.registerTool( get_node_info, { node_id: z.string().describe(Figma 节点 ID形如 100:200), file_key: z.string().describe(Figma 文件 Key) }, async ({ file_key, node_id }) { // 从内网 PostgreSQL 查询节点数据而不是请求公网 API const nodeData await db.query( SELECT data FROM figma_nodes WHERE file_key $1 AND node_id $2 , [file_key, node_id]); if (!nodeData?.rows?.[0]) { return { content: [{ type: text, text: Node ${node_id} not found in internal cache. }] }; } const node nodeData.rows[0].data; // 提取关键的样式与布局字段整理成易于 Agent 理解的文本 const summary extractNodeSummary(node); return { content: [{ type: text, text: JSON.stringify(summary) }] }; } );这里有一个很关键的思路MCP Tool 的返回值不一定要返回完整的原始 JSON而是可以返回“经过提炼的摘要”。Agent 的上下文空间有限如果一次调用返回几万行节点数据它反而会迷失。我在extractNodeSummary函数里做了字段白名单提取只把布局、样式、文本相关的关键字段输出给 Agent。实测下来这种方法让 Agent 生成代码的准确率比返回完整 JSON 高出不少。关于完整的 MCP Server 源码涉及内部封装不在这里全量贴出社区开源的改动版本很多读者按上述思路二开成本很低。4.3 将 MCP Server 接入 Claude Code 与 CursorMCP Server 跑起来之后下一步是让客户端能够连上它。Claude Code 的配置方式是在项目根目录或用户配置目录下的.mcp.json文件中添加服务配置。对于 HTTP 传输的 MCP Server配置示例{ mcpServers: { figma-intranet: { type: http, url: http://10.20.30.40:8900/mcp, headers: { Authorization: Bearer 内网生成的APIKey } } } }配置完之后在 Claude Code 里执行/mcp命令就能看到figma-intranet服务是否连接成功以及它暴露了哪些工具。Cursor 的配置方式类似在 Cursor 的 Settings → MCP 里新增 Server填入同样的 URL 和 Header 即可。有一点要注意Cursor 和 Claude Code 默认对 MCP 工具的调用策略不完全一样。Claude Code 更主动看到上下文相关就会调用Cursor 偶尔需要你在对话里明确“先调用 Figma MCP 工具读取设计稿信息”建议团队内部统一使用 Claude Code 作为主力客户端能减少很多无效沟通。4.4 Skill 层的封装与工作流设计MCP Server 部署完成后只是完成了“器官移植”Skill 负责让大脑学会使用这些器官。我用 Claude Code 的 Agent 能力做了一套“前端页面还原 Skill”它的工作流是这样的用户输入一句话例如“读取 figma://team-project/landing-page 这个文件生成一个 React 页面样式使用 Tailwind”。Agent 通过 MCP Toolget_file_structure获取文件的页面结构先输出整棵结构树让用户确认要还原的是哪个 Frame。通过get_node_info逐层读取相关 Frame 的布局和样式数据如果遇到复杂节点或需要视觉辅助的情况调用export_node_image导出节点图片加入对话上下文。Agent 综合所有信息后按照团队代码规范输出 React Tailwind 代码并在代码块之后附加一份“还原说明”列出还原尺寸、颜色、间距、字体等关键依据。Skill 的指令文件里有一个很容易踩坑的点不要过度限制 Agent 的输出格式否则遇到复杂设计稿时它会变得极其死板。我更建议在 Skill 里给出“必须包含的检查项”而不是“必须使用的措辞”。比如必须检查原始设计稿的间距与代码是否一致、字体大小是否精确到像素、颜色是否使用了设计 Token 变量、组件是否调用了组件库还是新建了 DOM 结构。这些检查项能拉高输出质量同时保留 Agent 的灵活性。Skill 本质上就是一份 Markdown 格式的指令文档团队内部用 git 管理即可。建议按技能粒度拆分为“页面还原”“组件抽取”“设计 Token 提取”“设计走查”等多份 Skill避免一个大 Skill 里装了太多任务导致指令互相干扰。5. 常见问题与排查技巧实录这套方案跑起来后我们在开发环境遇到的问题不少这里挑典型的记录下来给后来人当速查表。5.1 Figma Token 权限不足导致同步结果“缺胳膊少腿”第一次启动同步服务我只勾了File content: Read-only权限结果发现拉回来的节点树里图片资源的 URL 字段全是空。排查了半小时最后发现还需要File content: Read-only只覆盖了文件内容读取而图片导出需要额外的权限点。重新生成 Token勾选全部 File 相关只读权限后图片导出才正常。注意Figma Token 的权限点配置很细建议完整勾选File content: Read-only并在测试阶段用一个真实复杂的文件做全链路验证而不是拿一个只有矩形的小文件测试。小文件测不出权限覆盖的完整性。5.2 内网服务器无法访问公网 Figma API同步任务频繁失败这是模式 B 最常见的问题。有些内网机器能访问外网但访问出口要经过代理有些则是彻底断公网。我们后来统一给同步服务所在机器配置了企业代理环境变量export HTTP_PROXYhttp://proxy.corp.example.com:8080 export HTTPS_PROXYhttp://proxy.corp.example.com:8080同时在代码里对代理做了超时控制和重试机制。如果同步服务器彻底不能出网那就只能降级到模式 C离线导入或者由一台专用的边界机器完成拉取再转存内网。5.3 MCP Server 连接超时客户端提示“Connection closed”这个问题的根源往往是 MCP Server 和客户端之间的网络不稳定或者是服务启动时绑定了localhost而不是0.0.0.0。开发环境下我遇到过 Node 服务启动后只监听了 127.0.0.1客户端在其他机器上当然连不上。解决方法是启动时显式指定监听所有网卡node server.js --host 0.0.0.0 --port 8900另外MCP 的 HTTP 传输要求客户端和服务端之间保持长连接如果中间有负载均衡或防火墙设置了过短的空闲连接超时也会造成调用过程中突然断开。建议在内网搭建时直接把 MCP 端口在防火墙上设置为长期允许并避免经过 Nginx 超时拦截。5.4 解析出来的节点信息里Auto Layout 参数为空Auto Layout 是 Figma 中实现响应式布局的核心机制很多前端还原场景依赖它。但是如果你同步脚本用的是低版本的官方 REST API或者某些节点类型不是 Frame比如是 Instance 或 ComponentAuto Layout 字段解析可能拿不到。解决方式是解析时对几个关键的布局字段做“级联回退”先取当前节点的layoutMode如果为空就向上找父节点同时检查节点类型如果是INSTANCE需要额外读取其对应的组件定义Component Definition中的布局属性。这一步是很多解析方案忽略的地方也是解析还原度上拉开差距的地方。5.5 Skill 生成了代码但颜色值不是设计 Token这个问题出在 Skill 指令里Agent 并没有被要求优先使用设计 Token。第一次测试时Agent 拿到 Figma 里的#3B82F6就直接写进 Tailwind 类名里了而不是替换成团队的--color-primary变量。后来在 Skill 指令里加了一条强约束所有颜色、圆角、阴影必须优先映射到设计系统 Token如果无法映射输出时必须高亮提示。整改之后生成的代码才真正具备了落地价值。5.6 一份避坑清单场景坑点预防与修复Token 权限权限点不完整图片无法导出勾选全部只读文件权限用复杂文件全链路验证网络环境内网不能出公网同步失败配置代理或将同步服务放在边界机器MCP 绑定服务只监听本地地址启动参数显式绑定 0.0.0.0长连接负载均衡空闲超时导致断开防火墙放行 MCP 端口必要时调大超时Auto Layout实例节点拿不到布局参数级联向上查找父节点读取组件定义样式映射直接用色值而非设计 TokenSkill 指令强制映射 Token无法映射时高亮提示Node 版本低版本 Node 运行 MCP SDK 报错使用 Node 18 及以上版本6. 最后的实践经验总结整套方案跑下来我最真实的体会是MCP 和 Skill 都不难真正的难点在于把“设计稿的数据语义”和“AI 生成的代码语义”对齐。MCP Server 解决了取数的问题Skill 解决了编排的问题但取回来的数据能否被 Agent 正确理解取决于我们在返回摘要时是否做了业务语义层面的翻译。简而言之MCP 返回的不能是一堆原始 JSON而应该是一段“人话”比如“这是一个宽 120、高 40 的圆角按钮背景色为品牌蓝”。另外建议任何团队在正式推广前先在两条业务线上跑一个月的试用不要一开始就铺开。因为 Skill 这种问世的产物需要根据团队的真实 code review 反馈持续迭代。AI 生成的代码质量再高也要有人做技术兜底。我的经验是初期让资深前端担任 Agent 输出的质量看门人把常见的质量问题沉淀回 Skill 指令里几轮迭代之后AI 的产出会越来越稳定。最后再分享一个小技巧如果团队频繁使用 GitHub 这类代码托管平台建议推动 IT 部门部署内网 git 镜像缓存把依赖和模型指令的拉取走内网既快又稳。这个经验对整套方案的日常协作体验提升非常明显。