figma-to-code-mcp

为什么要做这个项目？

Figma To Code MCP 专注于仅提取大模型构建 UI 所需的信息，同时移除与代码生成无关的 Figma 专属元数据。结果如下：

• ✅ 文件体积减少 99.5%，适用于真实的 Figma 文件（65 MB → 128 KB）
• ✅ 字段简洁且可映射到 CSS（style.background、layout.direction、style.fontSize）
• ✅ 保留完整的 UI 构建数据（布局、样式、文本、组件）
• ✅ 节点级布局和样式，并在共享令牌注册表中提供可复用的值
• ✅ 省略 Figma 内部信息——不包含边界框或约束元数据
• ✅ 变量解析——将 Figma 变量解析为实际值
• ✅ 支持 SVG——将矢量图形导出到磁盘
• ✅ 模式折叠——去重重复的 UI 模式

---

通过这个模型上下文协议服务，让 Cursor 和其他 AI 编码工具访问你的 Figma 文件。

可用工具

工具	描述
get_figma_design	获取与 CSS 对齐、针对 LLM 优化的设计数据。导出 SVG 资源和 PNG 渲染图。
get_image_fills	从 Figma 文件中获取图片填充 URL
render_node_images	将 Figma 节点渲染为 PNG 图片

get_figma_design 会自动导出 SVG 资源。其响应包含 svgAssetsFolder 和相对文件名 svgPathInAssetFolder；将两者组合即可定位每个文件。使用 svgOutputDir 可将资源直接导出到指定的资源目录。它还会将请求的节点渲染为 1x PNG：其响应包含 renderedDesignNodeAssetsFolder 和文件名 renderedDesignNodePathInAssetFolder，可用来将构建结果与设计进行比较。没有单独注册的 read_vector_svg 工具。

默认情况下，get_figma_design 会在 componentSets 中返回设计使用的组件，每个组件集都包含 propKeys 和 propValues（各属性在该组件集成员中的取值）。每个组件集都会写入 componentSetsFolder 中各自的 JSON 文件，componentSets 会列出每个组件集的 file、propKeys 和 propValues。大于 228 KB 的组件集会变成以组件集命名的文件夹：其 file 为 <set>/index.json，其中列出各个变体；每个变体都会作为单独的 <nodeId>.json 文件放在该文件夹中，并将 : 替换为 -（例如 7-770.json）。COMPONENT_SET 根节点也采用相同的处理方式：当其变体超过 228 KB 时，children 会移出，root.file 指向 <name>/index.json，每个变体则作为 <variant name>.json 文件放在该文件夹中，因为根节点变体没有节点 ID。每个 file 值都相对于 componentSetsFolder，因此变体的文件路径是 <set>/<nodeId>.json，而不是相对于其组件集文件夹。若要从组件库构建组件，请传入 includeComponentVariants: true，以获取这些组件的所有其他变体（所有尺寸、颜色和状态），以及它们的属性和可获取的视觉素材。此操作会从 Figma 获取更多数据，并返回更大的响应。

使用 --skip-image-downloads 时，只会注册 get_figma_design；SVG 导出仍可用，但不会渲染节点 PNG。

所需权限范围

创建 Figma 个人访问令牌，并授予以下权限范围：

权限范围	用途
file_content:read	读取文件节点、布局和样式
library_content:read	读取已发布的组件/样式
library_assets:read	将引用的组件解析为其已发布的库来源
file_variables:read	读取变量（仅限 Enterprise，可选）
file_comments:read	读取附加到节点的评论（可选）

注意： 变量解析需要 Enterprise 计划。如果没有 Enterprise 计划，请设置 resolveVariables: false。

如果无法访问评论，提取过程会在不包含评论的情况下继续，并记录一条警告。

工作原理

1. 打开 IDE 的聊天窗口（例如 Cursor 中的 Agent 模式）。
2. 粘贴 Figma 文件、画框或分组的链接。
3. 要求 Cursor 实现设计。
4. Cursor 获取与 CSS 对齐且针对大模型优化的设计数据，并生成准确的代码。

根据设计构建页面的 Agent 应遵循 面向大模型 中的说明。

此 MCP 服务会将 Figma API 数据转换为便于大模型使用的格式：

• 精简的布局／样式字段（layout.direction、style.background、style.fontSize），而非冗长的 Figma 内部数据
• 节点级样式，每个不同的设计值都会引用 tokens 注册表中的条目
• 用于自动布局的 Flexbox 基元，以及用于叠加元素和自由形式图形的父级局部定位
• 完整的 UI 数据（颜色、排版、间距、效果）
• 体积缩减 99.5%，同时保留所有 UI 关键数据

当前响应使用架构 v3。 V3_CSS_PROPERTY_MAPPING.md 描述的是较早的 v2 映射，而非当前响应规范。

解读 v3 中的视觉细节

响应包含可选字段，用于表示无法通过单一文本样式或简单的弹性布局表达的细节：

字段	含义
textRuns	按顺序排列的文本范围及其标量样式覆盖，仅当字符样式不同时才会输出
layout.position	包含块使用 relative，非流式子元素使用 absolute
layout.left、layout.top	相对于直接父级坐标系的像素偏移量，包括零值和负值
style.borderWidths	非对称边框的明确上、右、下、左宽度，包括宽度为零的边缘
gradientHandlePositions	三个归一化的节点局部控制点，用于保留渐变的方向和几何形状
svgViewport	导出的 SVG viewBox 在节点局部像素坐标中的范围，包括节点原始画布以外的可见内容。x 或 y 为 0 时会省略；若缺失则表示为 0
renderedDesignNodePathInAssetFolder	renderedDesignNodeAssetsFolder 中所请求节点的 1x PNG 文件名，用于比较构建结果与设计

现有的完整 text 字段和节点级样式仍会保留。如果存在 textRuns，请按顺序渲染其中的文本片段，而不要再次渲染 text。先解析节点的基础排版 token，再应用每个文本片段的标量覆盖值。各片段的文本连接后与原始完整文本一致；普通文本片段继承基础样式。明确指定的 normal、none 和零值会重置继承的样式。

对于已定位的子元素，请保留输出中的包含块、本地尺寸和偏移量。真正的自动布局同级元素仍应处于弹性流中；覆盖通知、图表曲线和参考线可以共用一个绝对定位坐标空间。Figma 布局模式 NONE 不会转换为弹性列布局。

对于非对称描边，borderWidths 会替代统一的 borderWidth。仅将共享的 border 颜色应用于指定边缘；不要凭空添加包围盒边框。统一边框仍使用 borderWidth。

渐变控制点可能位于单位正方形之外；不要将其限制在正方形内，也不要舍弃它们并改用默认方向。

SVG 导出会保留原始节点局部坐标，并包含局部画布与可见几何的并集。每个导出节点的 svgViewport 都与文件的 viewBox 一致。将节点原始布局占位保留为包装层，然后把 SVG 或图像放置在 svgViewport.x / y 处（若缺失则为 0），并使用视口的 width / height。不要将这个扩展后的资源拉伸到节点原始尺寸：图表系列的可见内容边界可能不同，但必须共用同一局部坐标系。保留祖先级裁剪。纯色填充会烘焙到设计导出的资源中，因此外部图像也会保留其颜色。

面向 LLM

使用 get_figma_design 从 Figma 节点构建页面或组件时，请遵循本节内容。

响应概览

字段	含义
root	请求节点的设计树。普通框架会内联返回。包含大型变体的组件集根节点会拆分（请参阅解析组件文件）。
tokens	共享值。样式字段中保存着指向此注册表的键，例如 colors.sys.color.primary.default = #99121C。
componentSets	设计使用的每个组件集各有一个引用：file、propKeys、propValues。
componentSetsFolder	存放组件集 JSON 文件的文件夹。
svgAssetsFolder	存放导出的 SVG 文件的文件夹。每个矢量图的 svgPathInAssetFolder 都是此文件夹中的文件名。
renderedDesignNodeAssetsFolder, renderedDesignNodePathInAssetFolder	参考图片（见下文）。

响应内容很大。测试中的完整页面为 200–360 KB，因此请分段读取 root，不要一次性读取全部内容。

参考图片

renderedDesignNodePathInAssetFolder 是请求节点的 1x PNG 图片。它展示了 Figma 渲染出的设计，是构建和检查时的参考依据。

• 编写代码前先打开 PNG。对于组件集，它会以网格形式展示所有变体；对于框架，它会展示该框架。
• 利用图片将页面划分为多个部分，然后将每个部分与 root.children 中的对应部分匹配。
• 按相同宽度渲染你的构建结果，并逐部分与 PNG 对比。持续修正，直到差异消失或能够解释这些差异。
• 对于框架，PNG 的像素宽度等于框架的布局宽度（例如，410 px 宽的框架对应 410 px）。
• 如果服务使用 --skip-image-downloads 运行、Figma 未返回图片或下载失败，则不会提供 PNG。没有图片时，应说明已跳过视觉检查，而不是凭猜测判断。

流程：从设计到页面

1. 每个断点获取一个节点。 名为 Startseite (XS) 这样的画框对应一个断点。需要哪些断点，就分别获取。
2. 每个设计使用一个新的导出文件夹。 传入 svgOutputDir。该文件夹会接收 SVG、PNG 和 component-sets/。之前运行生成的文件会保留在其中，因此不要将同一个文件夹用于不同的设计。
3. 阅读参考图片，并列出页面的各个版块。
4. 规划组件。 每个重复版块或每个 component 名称对应一个组件。使用 componentSets[name].propValues 查看每个组件的变体选项。
5. 一次性映射设计令牌。 创建一个主题文件，将页面使用的每个令牌键映射到 CSS 变量或主题值。不要将十六进制值复制到每个元素中。
6. 逐个版块构建。 将 layout 映射到 flex：direction、gap、padding、width、height、grow、align 和 justify。仅当 layout.position 为 absolute 时才使用绝对定位，left 和 top 的值相对于父级。
7. 根据 text 渲染文本。 如果存在 textRuns，则在基础排版令牌上按顺序渲染其中的文本片段，不要再次渲染 text（参见解读视觉细节）。
8. 根据视口放置矢量图。 对于每个矢量图，从 svgAssetsFolder 加载由 svgPathInAssetFolder 指定的文件。将其放置在 svgViewport.x 和 y 处（缺失的值按 0 处理），并将其尺寸设为 svgViewport.width 和 height。不要将其拉伸至节点尺寸。
9. 处理图像填充。 如果节点使用图像填充（例如照片或截图），请调用 get_image_fills 获取其下载 URL。
10. 按照上述说明对照参考图片验证构建结果。
11. 如果目标技术栈、断点或预期输出不明确，请先询问，不要猜测。

解析组件文件

• root.file、componentSets[name].file 以及 index.json 中的 file 条目均相对于 componentSetsFolder。将它们与该文件夹路径拼接，而不要猜测文件位置。
• 文件名由名称转换而来：将每段非 A–Z、a–z、0–9 和 _ 字符替换为一个 -。例如，Variant=Start 1, Color=Default 会变为 Variant-Start-1-Color-Default.json，节点 7:770 会变为 7-770.json。
• 按原样使用 componentSets 中的键。键可能包含方括号括起的库引用，例如 headline-combo [zd1Yd…/3574:6]。请读取 file 的值，不要根据键构造路径。

注意事项

• Root node … not found：节点 ID 有误或文件无法读取。将 URL 中的 node-id=519-8870 转换为 519:8870，并检查该文件中是否存在此节点。
• 重复调用：对于相同输入，服务会将设计缓存 5 分钟。保留首次响应，不要再次获取。更改 includeComponentVariants、resolveVariables 或凭据会触发重新获取。
• interactions 描述原型的悬停和点击目标。除非构建需要这些行为，否则请忽略。

入门指南

许多代码编辑器和其他 AI 客户端使用配置文件来管理 MCP 服务。

此服务需要 Node.js 18 或更高版本。

可以将以下内容添加到配置文件中，以配置 tmegit-figma-to-code-mcp 服务。

MacOS / Linux

{
  "mcpServers": {
    "Figma To Code MCP": {
      "command": "npx",
      "args": ["-y", "@tmegit/figma-to-code-mcp", "--figma-api-key=YOUR-KEY", "--stdio"]
    }
  }
}

Windows

{
  "mcpServers": {
    "Figma To Code MCP": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@tmegit/figma-to-code-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}

或者，也可以在 env 字段中设置 FIGMA_API_KEY 和 PORT。

HTTP 模式

省略 --stdio，即可在 /mcp 提供 Streamable HTTP 服务，并在 /sse 提供旧版 SSE，消息则发送到 /messages。并发客户端拥有彼此独立的 MCP 会话；关闭一个会话不会关闭其他会话。使用相同已配置凭据的会话会共享库变量预取结果。

用于嵌入时，startHttpServer(host, port, server) 仍接受由此软件包的 createServer 返回的服务。对于自定义 McpServer，请将每会话工厂作为第三个参数传入，以支持并发客户端；单个外部实例仍仅支持单个会话。

createServerFactory(auth, options) 会一次性准备共享配置。如果添加自定义工具，请在工厂返回的每个服务上注册这些工具：添加到单个已提供实例的注册不会复制到它生成的其他实例。自定义异步工厂必须完成执行，以便关闭时能够清理待处理的连接。

默认主机为 127.0.0.1。这些端点不提供客户端身份验证；若没有经过身份验证的代理，请勿将其暴露给不受信任的网络。

配置

服务从 CLI 标志和环境变量读取配置。如果两者均已设置，则以 CLI 标志为准。

选项	CLI	环境变量	默认值
Figma API 密钥	--figma-api-key	FIGMA_API_KEY	必填
Figma OAuth 令牌	--figma-oauth-token	FIGMA_OAUTH_TOKEN	未设置
端口	--port	FIGMA_TO_CODE_MCP_PORT 或 PORT	3333
主机	--host	FIGMA_TO_CODE_MCP_HOST	127.0.0.1
输出格式	--json	OUTPUT_FORMAT	yaml
跳过图像工具和节点 PNG	--skip-image-downloads	SKIP_IMAGE_DOWNLOADS=true	false
SVG 输出目录	--svg-output-dir	FIGMA_SVG_OUTPUT_DIR	临时目录
预取库变量	--library-file-keys	FIGMA_LIBRARY_VARIABLE_PREFETCH_FILE_KEYS	未设置
缓存路径	--library-cache-path	FIGMA_MCP_CACHE_PATH	临时缓存文件
缓存 TTL	n/a	FIGMA_MCP_CACHE_TTL_MS	7 days
强制刷新缓存	n/a	FIGMA_MCP_REFRESH_CACHE	关闭

说明：

• --library-file-keys 和 FIGMA_LIBRARY_VARIABLE_PREFETCH_FILE_KEYS 接受以逗号分隔的 Figma 库文件密钥。
• FIGMA_MCP_CACHE_PATH 可以指向 JSON 文件或目录。服务会在 .json 前添加凭据指纹，以隔离缓存的库变量。例如，目录中的文件名为 figma-mcp-library-cache.<fingerprint>.json。服务启动时不会复用现有的未限定缓存文件。
• 只有配置了库文件密钥时，才会使用库缓存。
• 即使缓存文件已存在，FIGMA_MCP_REFRESH_CACHE 也会强制在启动时重新获取数据。

.env 示例：

FIGMA_API_KEY=your_figma_pat
# prefetch variables (tokens etc) from specific library files on startup to avoid T2 calls during design fetch
FIGMA_LIBRARY_VARIABLE_PREFETCH_FILE_KEYS=abc123,def456
FIGMA_MCP_CACHE_PATH=./cache
FIGMA_MCP_CACHE_TTL_MS=604800000
# Uncomment to force cache refresh on next startup
# FIGMA_MCP_REFRESH_CACHE=1

API 调用与速率限制

缓存未命中时，get_figma_design 可能会进行以下 API 调用：

端点	层级	调用时机
GET /v1/files/{fileKey}/nodes	T1	获取请求的设计节点及其矢量几何信息
GET /v1/images/{fileKey}	T1	将请求的节点渲染为 1x PNG；失败不会影响整体流程
GET /v1/files/{fileKey}/variables/local	T2	当 resolveVariables=true 时
GET /v1/files/{fileKey}/comments	T2	尝试获取评论；失败不会影响整体流程
GET /v1/components/{key}	T3	发现尚未被任何列表覆盖的组件键所属的库
GET /v1/files/{fileKey}/components	T3	列出此文件及每个已发现库中已发布的组件，每个库仅调用一次
GET /v1/files/{libFileKey}/nodes	T1	获取源组件定义，按库分批

请求数量会随唯一组件键、库、节点批次和重试次数而变化。支持来自多个库的组件；如果库元数据不可用，则会回退到可用的实例数据。

请求会按 Figma 的层级进行限速，确保每个层级不超过其每分钟配额（Professional Dev/Full 席位的 T1、T2 和 T3 分别为 10、25 和 50 次请求）。如果 Figma 仍返回 429，则仅暂停该层级，等待 Retry-After 指定的时间，然后重试请求，最多重试三次。网络层面失败的 GET 请求会通过 curl 重试一次，这有助于在企业代理环境中使用。重试会占用同一个请求时段，因此在层级配额中仍只计为一次。

兼容的设计缓存命中可避免这些 Figma 调用，但仍会将资源（包括节点 PNG）导出到指定目录。PNG 从 Figma 的图片 URL 下载，不属于 Figma API 调用。更改凭据或会影响结果的选项时，不会复用不兼容的设计响应。

有效样式从节点属性中读取，包括节点特定的覆盖值。该工具不会单独发起 /styles 请求。为保持兼容性，库现有的 fetchStyles 导出和 styleMap 参数仍可使用；设计响应目前不会输出共享样式名称。

Professional 方案搭配 Dev/Full 席位：10 次请求/分钟（T1）、25 次请求/分钟（T2）、50 次请求/分钟（T3）。

Star 历史

致谢

本项目最初受到 GLips 开发的原始 Figma Context MCP 中相关理念的启发： https://github.com/glips/figma-context-mcp

原项目提供了一个 Model Context Protocol（MCP）服务，可简化 Figma 数据，以便 AI 编码 Agent 使用。本实现已采用不同的数据模型、API 和处理方式进行了大幅重新设计，应视为一个独立系统。