Skip to content

Pactortester/figma-mcp-cached

BranchesTags

Repository files navigation

Figma-Context-MCP-Cached

Figma Context MCP Logo

English Version: README_EN.md

基于 Figma Context MCP 的增强版本，通过本地持久化缓存显著减少对 Figma API 的请求次数，从而缓解速率限制问题，提升稳定性与响应速度。

该版本特别适合 免费 Figma 账号、高频上下文请求、以及 Cursor / MCP 客户端 场景。

✨ 特性

  • ✅ 支持 Figma 文件内容本地缓存
  • ✅ 显著减少 API 请求次数，缓解速率限制
  • ✅ 可配置缓存有效期（TTL）
  • ✅ 支持自定义缓存目录
  • ✅ figma_prepare_file 工具：智能准备和缓存 Figma 文件
  • ✅ 支持 nodeId 检查：确保指定的节点存在于缓存中
  • ✅ 支持强制刷新：通过 forceRefresh 参数强制获取最新设计数据
  • ✅ 智能下载路径：图片下载默认保存到系统下载文件夹（支持 Windows/macOS/Linux）
  • ✅ 优化的 LLM 调用引导：自动引导正确的工具调用顺序
  • ✅ 完全兼容原有 MCP 接口与调用方式
  • ✅ list_cache 工具：查看缓存状态和统计信息
  • ✅ cleanup_cache 工具：清理过期和损坏的缓存文件
  • ✅ 自动缓存清理：定时清理过期缓存，保持磁盘空间整洁
  • ✅ LRU 内存缓存：智能内存缓存，避免重复磁盘 I/O
  • ✅ 节点级别缓存：内存中缓存已解析的节点数据
  • ✅ 可选缓存加密：支持 AES-256-CBC 加密保护敏感设计数据
  • ✅ 适用于 Cursor 等 MCP 客户端

🚀 快速开始（30 秒上手）

1. 获取 Figma API Key

访问 Figma 开发者设置 创建 Personal Access Token。

2. 配置 MCP（以 Cursor 为例）

在 Cursor 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "Figma-Context-MCP-Cached": {
      "command": "npx",
      "args": [
        "-y",
        "@pactortester/figma-mcp-cached",
        "--stdio",
        "--figma-api-key=YOUR_FIGMA_API_KEY",
        "--figma-caching={\"ttl\":{\"value\":7,\"unit\":\"d\"}}"
      ]
    }
  }
}

3. 开始使用

在 Cursor 中直接粘贴 Figma 链接，AI 会自动：

  1. 调用 figma_prepare_file 准备文件
  2. 调用 get_figma_data 获取设计数据

💡 提示：首次请求会从 Figma API 获取数据并缓存，后续请求直接从本地缓存读取，速度提升 10 倍以上！

📦 Figma 缓存机制说明（重要）

⚠️ 请在设计相对稳定或已定稿后再启用缓存功能 本 MCP 默认支持对 Figma API 返回结果进行缓存（可配置 TTL），以减少 API 请求次数、提升响应速度并避免触发 Figma 的限流策略。

✅ 缓存的优势

  • 显著提升 MCP 响应速度
  • 降低 Figma API 调用频率
  • 适合已定稿或低频变更的设计文件

⚠️ 潜在风险（请务必注意）

由于缓存机制的存在：

  • 当 Figma 页面或组件发生更新时
  • 在缓存未过期（TTL 内）
  • MCP 可能仍返回 旧的设计数据
  • 无法立即反映最新的设计变更

这在以下场景中尤为明显：

  • 页面结构调整
  • 组件属性修改
  • 新增 / 删除节点
  • 文案或布局的细微更新

✅ 使用建议（强烈推荐）

  • ✅ 设计定稿后 或 变更频率较低时 再启用缓存
  • ✅ 代码生成、设计评审、设计回溯等场景非常适合缓存
  • ❌ 设计频繁调整阶段不建议启用缓存

📜 开发脚本说明

详细的 NPM Scripts 使用指南请查看 SCRIPTS.md，包含：

  • 构建和开发命令
  • 版本管理脚本（一键更新版本号）
  • 发布流程说明
  • 常用工作流示例

🚀 使用方式

命令行参数（适合 MCP 市场托管）

基础配置

{
  "mcpServers": {
    "Figma-Context-MCP-Cached": {
      "command": "npx",
      "args": [
        "-y",
        "@pactortester/figma-mcp-cached",
        "--stdio",
        "--figma-api-key=YOUR-KEY",
        "--figma-caching={\"ttl\":{\"value\":30,\"unit\":\"d\"}}"
      ]
    }
  }
}

完整配置（包含所有可选项）

{
  "mcpServers": {
    "Figma-Context-MCP-Cached": {
      "command": "npx",
      "args": [
        "-y",
        "@pactortester/figma-mcp-cached",
        "--stdio",
        "--figma-api-key=YOUR-KEY",
        "--figma-caching={\"ttl\":{\"value\":30,\"unit\":\"d\"},\"cacheDir\":\"~/figma-cache\",\"autoCleanup\":true,\"cleanupInterval\":{\"value\":1,\"unit\":\"h\"},\"maxMemoryCacheSize\":200,\"encryptionKey\":\"your-secret-key\"}"
      ]
    }
  }
}

优先级说明： 命令行参数 > 环境变量

字段说明：

ttl（必填）

控制缓存的有效期。

  • value：数值
  • unit：时间单位，可选值：
    • ms（毫秒）
    • s（秒）
    • m（分钟）
    • h（小时）
    • d（天）

cacheDir（可选）

控制缓存文件的存储目录。

  • 相对路径：相对于当前工作目录
  • ~ 会解析为用户主目录

默认缓存路径：

  • Linux：~/.cache/figma-mcp
  • macOS：~/Library/Caches/FigmaMcp
  • Windows：%LOCALAPPDATA%/FigmaMcpCache

autoCleanup（可选）

是否启用自动清理过期缓存。默认为 true。

  • true：自动定时清理过期缓存文件
  • false：禁用自动清理（需手动调用 cleanup_cache 工具）

cleanupInterval（可选）

自动清理的执行间隔。默认为每小时一次。

  • value：数值
  • unit：时间单位（同 ttl）

maxMemoryCacheSize（可选）

内存中缓存的最大条目数（LRU 淘汰）。默认为 100。

设置为较小的值可以减少内存占用，设置为较大的值可以提高缓存命中率。

encryptionKey（可选）

缓存文件加密密钥。设置后，所有缓存文件将使用 AES-256-CBC 加密存储。

适用于保护敏感设计数据的场景。密钥应妥善保管，丢失密钥将无法读取已加密的缓存。

🧠 缓存行为说明

当启用缓存后：

  1. MCP Server 首次请求某个 Figma 文件时：

    • 从 Figma API 拉取完整文件
    • 将结果写入本地缓存

  2. 在缓存未过期前：

    • get_figma_data 请求将直接从本地缓存返回，不再重复请求 Figma API

  3. 当缓存过期：

    • 自动重新拉取并更新缓存

🔄 强制刷新缓存

  • 推荐方式：调用 figma_prepare_file 时设置 forceRefresh: true，或告诉 LLM "拉取最新数据"
  • 手动方式：删除 cacheDir 中对应的缓存文件

🛠️ MCP Tools 详细说明

本项目提供三个 MCP 工具，用于与 Figma 设计文件交互。

1️⃣ figma_prepare_file - 文件准备工具

智能文件准备工具，用于在获取 Figma 数据之前确保文件已准备好。

主要特性：

  • ✅ 自动缓存检查：检查文件是否已缓存且有效
  • ✅ nodeId 验证：如果提供了 nodeId，会验证该节点是否存在于缓存中
  • ✅ 智能刷新：如果缓存过期或 nodeId 不存在，自动重新拉取文件
  • ✅ 强制刷新：支持强制拉取最新数据，绕过缓存
  • ✅ 缓存未启用提示：即使缓存未启用，也会提供明确的提示信息

工具参数：

参数 类型 必填 说明
figmaUrl string ✅ Figma 设计文件 URL，支持格式：https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>
forceRefresh boolean ❌ 设为 true 时强制从 Figma API 拉取最新数据，绕过缓存。当用户明确要求获取最新数据或设计刚更新时使用

使用方式：

当用户提供 Figma URL 时，LLM 会自动：

  1. 首先调用 figma_prepare_file 准备文件
  2. 然后调用 get_figma_data 获取数据
用户提供 URL → figma_prepare_file (准备文件) → get_figma_data (获取数据)

强制刷新示例：

{
  "figmaUrl": "https://www.figma.com/design/xxx/...",
  "forceRefresh": true
}

用户可以通过以下方式触发强制刷新：

  • "帮我拉取最新的设计稿"
  • "刷新一下这个 Figma 文件"
  • "设计刚更新了，重新获取一下"

返回值说明：

  • 缓存已存在且有效：返回提示信息，不拉取数据
  • 缓存不存在或过期：自动拉取并缓存文件
  • nodeId 不存在：重新拉取文件并验证 nodeId
  • 强制刷新：直接从 API 拉取最新数据并更新缓存
  • 缓存未启用：返回警告信息，提示需要配置缓存

2️⃣ get_figma_data - 获取 Figma 数据

获取 Figma 文件的完整设计数据，包括布局、内容、视觉样式和组件信息。

⚠️ 重要：调用此工具前，必须先调用 figma_prepare_file 准备文件。

工具参数：

参数 类型 必填 说明
fileKey string ✅ Figma 文件的 key，通常在 URL 中：figma.com/design/<fileKey>/...
nodeId string ❌ 要获取的节点 ID，格式如 1234:5678 或 1234-5678。如果 URL 中包含 node-id 参数则必须使用
depth number ❌ 遍历节点树的深度。除非用户明确要求，否则不要使用此参数

使用示例：

{
  "fileKey": "QlQwKAl9abcdhvlfvpM5K",
  "nodeId": "2777:9428"
}

返回数据：

  • metadata：文件元数据
  • nodes：节点树结构，包含布局、样式、文本等信息
  • globalVars：全局样式变量（复用的样式会被提取为变量）
  • components：组件定义
  • componentSets：组件集定义

3️⃣ download_figma_images - 下载 Figma 图片

从 Figma 文件中下载 SVG 和 PNG 格式的图片资源。

工具参数：

参数 类型 必填 说明
fileKey string ✅ Figma 文件的 key
nodes array ✅ 要下载的节点数组（详见下方）
localPath string ❌ 图片保存目录的绝对路径。不提供时默认保存到系统下载文件夹
pngScale number ❌ PNG 图片的导出倍率，默认为 2（2x）

nodes 数组中每个元素的参数：

参数 类型 必填 说明
nodeId string ✅ 节点 ID，格式如 1234:5678 或 1234-5678
fileName string ✅ 保存的文件名，必须以 .png 或 .svg 结尾
imageRef string ❌ 图片填充的引用 ID。如果节点使用图片填充则必须提供；下载 SVG 矢量图时留空
needsCropping boolean ❌ 是否需要根据变换矩阵裁剪图片
cropTransform array ❌ Figma 变换矩阵，用于图片裁剪
requiresImageDimensions boolean ❌ 是否需要返回图片尺寸信息（用于生成 CSS 变量）

使用示例：

{
  "fileKey": "QlQwKAl9abcdhvlfvpM5K",
  "nodes": [
    {
      "nodeId": "2777-9428",
      "fileName": "hero-image.png"
    },
    {
      "nodeId": "2777-9430",
      "fileName": "icon-star.svg"
    }
  ],
  "pngScale": 2
}

默认下载路径：

  • macOS: ~/Downloads
  • Linux: ~/Downloads
  • Windows: C:\Users\<username>\Downloads

返回信息：

  • 下载成功的图片数量
  • 保存路径
  • 每张图片的文件名、尺寸、是否裁剪等信息

4️⃣ list_cache - 查看缓存状态

列出并显示当前缓存状态，包括缓存文件、总大小、缓存目录和 TTL 配置。

工具参数： 无

返回信息：

  • enabled：缓存是否已启用
  • cacheDir：缓存目录路径
  • fileCount：缓存文件数量
  • totalSize：人类可读的总缓存大小
  • ttl：人类可读的 TTL 时长

使用示例：

{}

示例响应：

{
  "enabled": true,
  "cacheDir": "~/Library/Caches/FigmaMcp",
  "fileCount": 5,
  "totalSize": "15.7 MB",
  "totalSizeBytes": 16462643,
  "ttl": "7d",
  "ttlMs": 604800000
}

5️⃣ cleanup_cache - 清理缓存

清理过期和损坏的缓存文件。此工具会删除超过 TTL（生存时间）的缓存文件以及任何损坏的缓存条目。

工具参数： 无

返回信息：

  • deletedFiles：删除的文件数量
  • previousSize：清理前的缓存大小
  • currentSize：清理后的缓存大小
  • currentFileCount：剩余缓存文件数量

使用示例：

{}

⚠️ 注意事项

  • 如果未设置 FIGMA_CACHING（环境变量或命令行参数），则保持 原始不缓存行为
  • 缓存的是 完整 Figma 文件数据
  • 命令行参数优先级高于环境变量
  • 工具调用顺序：当用户提供 Figma URL 时，LLM 会自动先调用 figma_prepare_file，再调用 get_figma_data
  • 非常适合：
    • 免费 Figma 账号
    • 频繁上下文读取
    • LLM / MCP 自动化场景
    • MCP 市场托管（通过命令行参数配置，无需服务器端环境变量）

📦 兼容性

  • ✅ 完全兼容原 Figma Context MCP
  • ✅ 无需修改客户端调用逻辑
  • ✅ 可作为原项目的 drop-in 替换

📋 更新日志

查看完整更新日志请访问 CHANGELOG.md

📄 License

本项目基于 MIT License 开源。

🙌 致谢

本项目基于以下开源项目进行开发与优化，在此表示感谢：

感谢上述项目提供的核心实现与设计思路。本项目在其基础上引入了本地持久化缓存机制，以提升性能并缓解 Figma API 的速率限制问题。

About

Cache‑enabled Figma Context MCP with persistent disk caching to reduce API rate limits and improve performance.

Topics

mcp figma 429 figma-mcp-cached

Resources

Readme

License

MIT license
Activity

Stars

60 stars

Watchers

0 watching

Forks

6 forks
Report repository

Releases 1

v1.1.0 Latest
Jan 19, 2026

Packages

 
 
 

Contributors

Languages