Figma CodeKit MCP

figma-codekit-mcp

从较早的包名升级：将 MCP 客户端命令中的包替换为 npx -y figma-codekit-mcp@latest。现有环境设置和保存的数据仍然兼容。

Figma → 真正经过设计校验的代码。

大多数 Figma 转代码工具在生成时就到此为止：它们交给你 JSX，然后就不管了。没有人会渲染输出并与画板进行比较，因此结果总是停留在“差不多有 90% 了”，而你得花一下午凭感觉调整内边距。

这个 MCP 服务补上了这一步。它会将画板确定性地转换为自包含 HTML（不使用大模型，不会虚构布局），然后在 Chromium 中渲染你的代码，与 Figma 参考图进行像素差异比较，测量每个元素的边框，并准确指出缺少或错位的内容。Agent 修改代码，再次调用 verify，并不断重复，直到差异降至抗锯齿误差范围内。

Figma 参考图	首次生成 — 差异为 5.18%	像素差异图	收敛 — 0.00%

这些都是运行 npm run example 得到的真实产物，它会在无需 API 密钥的情况下端到端运行整个循环。这个演示中的 generate 回调是大模型的脚本化替身，因此它如实展示了循环机制——测量是真实的，“模型”则不是真实的。

为什么 verify 步骤很重要

Figma 节点树会告诉你设计师声明了什么，但不会告诉你浏览器会如何处理你的 CSS。两者经常不一致——flex 间距可能会塌陷，字体可能会回退，绝对定位的子元素可能会脱离父元素。要弄清楚，唯一的方法就是渲染出来查看。

每轮中，figma_verify 会为 Agent 提供三个独立信号：

• 像素差异 — 整体不匹配比例以及差异最大的区域，让它知道错得有多严重以及问题在哪里。
• 元素边框交并比（IoU） — 每个 IR 节点都会带有 data-ir-id 标记，在实时 DOM 中测量后与其 Figma 边框进行匹配。这能将“左下角看起来不对”转化为“CTA 按钮缺失”或“价格标签低了 40px”。
• 绘制顺序和裁剪 — Figma 按从后到前的顺序列出子元素，因此节点的先序遍历索引就是其绘制顺序；通过在采样网格上调用 elementsFromPoint，可以获取实际重叠元素的渲染顺序。这样能捕获前两种信号本身无法发现的一类问题：元素都存在、边框位置也完全正确，但堆叠顺序相反——或者被祖先元素的 overflow 裁掉，而设计中允许它们溢出。两者都不会移动边框；对于高画板，也不会显著改变差异比例，但装饰性叠加层画在照片上而不是下方，却是人们一眼就能看到的问题。即使像素差异已经收敛，也会报告 WRONG STACKING / OVER-CLIPPED。

工具

工具	功能	网络
figma_convert	获取一个画框 → 生成自包含 HTML、ir.json、以数据 URI 表示的资源和 reference.png。可选启用 react: true（组件及其导入的 components/）和 next: true（可运行的 App Router 项目），还可生成响应式变体。	Figma API（已缓存）
figma_verify	在 Chromium 中渲染 HTML，与参考图进行像素差异比较，检查每个元素的 IoU、绘制顺序和裁剪情况，并返回有针对性的修复说明。	无
figma_inspect	将 IR 打印为缩进大纲（角色、边框、布局、文本、令牌），支持筛选——无需将原始 Figma JSON 倾倒到上下文中，即可读取结构。	无

响应式输出取决于设计实际声明的内容

responsive: true 会读取 Figma 中的尺寸意图——FILL 转为 flex/100%，HUG 转为 fit-content，FIXED 保留其 px 值。这只适用于设计师使用了 Auto Layout 的部分。

根节点未使用 Auto Layout 的画框就是画布：每个子元素都通过 position:absolute 定位在 1440px 画板的坐标上。没有任何内容可以调整，因此将根节点设为 width:100% 并不会让布局 重新流动——子元素仍固定在画布坐标上，右侧内容会被 overflow:hidden 隐藏。这看起来就像 页面在缩放时发生了错乱。

对于这类画框，转换器会保留原始画布，并将其缩放至视口大小，因此设计在各种宽度和缩放 级别下都能保持完整（最低缩至 0.5x，之后页面会滚动）。figma_convert 会告诉你它使用了 哪种策略。如果你希望布局真正重新流动，而不是按比例缩放，请在 Figma 中添加 Auto Layout—— 这是转换器需要的信号。

每个工具返回的都是文件路径和数字，绝不会返回大型数据块。转换后的画框通常包含 100+ KB 的 HTML；通过工具结果传递这些内容只会白白消耗 Agent 的上下文。Agent 会直接读取和编辑文件。

Figma 响应会按画框缓存，因此首次运行 figma_convert 后，整个流程都可以离线且免费运行—— 即使受到速率限制也不例外。

快速开始

你需要一个 Figma 个人访问令牌：Figma → Settings → Security → Personal access tokens，范围为 File content: read。

export FIGMA_TOKEN=figd_REPLACE_WITH_YOUR_TOKEN

将其添加到 Claude Code：

claude mcp add figma --env FIGMA_TOKEN=$FIGMA_TOKEN -- npx -y figma-codekit-mcp@latest

或者，为任何读取 JSON 配置的 MCP 主机添加：

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-codekit-mcp@latest"],
      "env": { "FIGMA_TOKEN": "figd_REPLACE_WITH_YOUR_TOKEN" }
    }
  }
}

然后，在 Agent 中复制 Figma 画框链接（右键点击画框 → Copy link to selection），并说 “转换此画框并进行验证，直到结果收敛。”

检查设置

FIGMA_TOKEN=$FIGMA_TOKEN npx -y figma-codekit-mcp@latest --check

它会检查 Node、是否找到了令牌（以及令牌的位置，但绝不会显示令牌值）、Figma 是否接受该令牌， 以及用于渲染 figma_verify 的 Chromium 是否已安装，然后打印 READY 或需要修复的内容。退出 代码 0 表示三个工具都能正常工作。如果缺少 Chromium（下载被跳过，或在 CI 环境中），请使用 npx -y figma-codekit-mcp@latest --install-browser 安装。

Windows

npx 会解析为 npx.cmd，某些 MCP 主机无法直接启动它。如果服务无法启动，请明确指定该 shim：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "figma-codekit-mcp@latest"]
}

具体流程

figma_convert  →  generated.html, reference.png, ir.json   (deterministic, no LLM)
      ↓
figma_verify   →  "NOT CONVERGED — 4.93% of pixels differ.
                   Elements: 22/26 match — 1 missing, 3 misplaced.
                   MISSING: button 'Get started'
                   MISPLACED: h1 'Pricing plan' — 6px too high"
      ↓
  agent edits generated.html
      ↓
figma_verify   →  "CONVERGED — 0.31% of pixels differ (threshold 2.00%)."

优化循环由调用方 Agent运行，而不是由服务内部的大模型运行。这意味着无需 ANTHROPIC_API_KEY，无需为第二个模型付费，而且 Agent 会完整保留已尝试过的内容。无头优化 循环（src/refine/）仍可供库使用。

无需 Agent 即可观察循环

同一条流水线还提供一个单页本地 Web 前端，分为两部分：左侧是聊天界面，右侧是生成的应用。发送一个画框链接后，它会询问要构建什么——HTML、React 还是 Next.js；精确还原还是响应式布局——然后在你面前完成转换、渲染和差异比对。右侧窗格会显示运行中的应用、源文件、验证数据和像素差异。

npm run site        # http://localhost:5173

它使用相同的 .figma-token 和 .figma-cache/，因此你之前转换过的画框可以在离线状态下于约一秒内重新运行。适合在让 Agent 处理画框之前，先检查它能否顺利转换；也适合向他人展示“已根据设计完成验证”意味着什么，而不只是口头描述。详情请参阅 site/README.md。

配置

变量	用途
FIGMA_TOKEN	必需。也会从项目目录中的 .figma-token 文件读取。FIGMA_API_KEY 也可作为别名使用。
FIGMA_MCP_CACHE_DIR	转换后的画框缓存位置。默认值为启动服务所在目录中的 .figma-cache/。
ANTHROPIC_API_KEY / GEMINI_API_KEY	可选，仅用于无头优化循环。MCP 服务不会调用大模型。
FIGMA_MCP_SKIP_BROWSER_DOWNLOAD=1	安装时跳过 Chromium 下载。figma_convert 和 figma_inspect 仍可使用；figma_verify 则不可用。

请参阅 .env.example。将 .figma-cache/ 添加到项目的 .gitignore 中——带有嵌入式资源的缓存画框大小可达数十 MB。

它不做什么

坦诚说明这些限制，因为它们源于 Figma，并非程序错误：

• 除非使用 Enterprise，否则设计令牌会解析为字面值。 Figma Variables REST API 仅限 Enterprise 使用。没有该 API 时，颜色和间距会输出为确切值，而不是 var(--color-surface)。其他功能均正常。
• 组件的 prop 绑定需要 Code Connect。 系统会按名称匹配并报告组件，但 API 不会公开由哪个实例 prop 驱动了哪个值。
• 差异比对存在误差下限。 即使完全匹配，抗锯齿和字体微调也会使比率维持在约 0.5–1.5%。因此，threshold 默认设为 2%——追求 0 就是在追逐渲染噪声。
• 一次处理一个画框。 按设计不支持遍历整个文件：这样可以让令牌消耗和 Figma 速率限制压力保持可预测。

将其用作库

验证循环与框架无关，也不需要 MCP 层：

import { verifyLoop } from 'figma-codekit-mcp';
import fs from 'node:fs';

const result = await verifyLoop({
  initialCode: firstPassHtml,
  referencePng: fs.readFileSync('frame.png'),
  ir,                                   // enables element-level IoU findings
  viewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
  threshold: 0.02,
  maxIterations: 5,
  generate: async ({ code, correction }) => callYourModel({ code, correction }),
});

console.log(result.converged, result.diffRatio);
fs.writeFileSync('diff.png', result.bestDiffPng);

循环会保留截至目前的最佳迭代结果，因此后续回归不会让结果变差。若要在开发服务器上验证 React 组件，而非 HTML 字符串，请传入 render: () => renderUrl('http://localhost:3000/preview', viewport)。

开发

git clone https://github.com/Mehmoodqureshi/figma-codekit-mcp.git
cd figma-codekit-mcp
npm install          # also downloads Chromium via postinstall
npm test             # full chain against a mocked Figma API — no token, no network
npm run example      # the verify loop end to end; watch the diff ratio fall
npm run serve        # run the MCP server on stdio

路径	作用
src/mcp/	MCP 服务、Figma REST 数据源、画框加载、资源导出
src/ir/	Figma 节点树 → 规范化 IR（角色、边框、自动布局、样式、令牌）
src/codegen/	IR → HTML / React / CSS
src/render.js src/diff.js src/elementDiff.js src/paintOrder.js	Playwright 渲染、像素差异、边界框 IoU、z-order + 裁剪
src/correction.js src/verifyLoop.js	将差异转换为修复指令；驱动循环
src/refine/	可选的无头大模型优化器（Anthropic、Gemini）
example/	可运行的演示和离线测试套件

example/ 同时也是测试套件——npm test 会针对模拟的 Figma REST API 运行完整的 loadFrame → figmaToIR → generateHtml 流程，其中包括速率限制处理以及旋转/镜像变换。无需令牌、网络或浏览器，因此每次推送时都可在 CI 中运行。

相关项目

• MCP Browser Extension (mcp-browser-extension)：让 Claude、Cursor 或任何 MCP Agent 使用你已登录的 Chrome，并采用默认拒绝所有域名的允许列表。

许可证

MIT © Mehmood Ur Rehman Qureshi