Figma Console MCP Server

你的设计系统即 API。 Model Context Protocol 服务器，桥接设计与开发——为 AI 助手提供对 Figma 的完整访问，用于提取、创建、调试和双向令牌同步。

🆕 设计系统提取（v1.40.0）： 将生产代码库转化为设计系统。七个新的 figma_ds_* 工具（本地模式）可扫描一个或多个应用代码库——检测框架、样式方法和供应商层；生成按使用频率排序的组件清单，并将其分类为 vendored / wrapped / pure-vendor / bespoke；从真实调用点推断变体；检测重复；并进行架构分析，将 UI kit 与设计系统区分开来（FollowButton 实际上是 Button——这里是缺失的通用原语）。然后，它们将应用事实上的样式挖掘为带逐令牌来源的 DTCG 令牌——多模式 CSS 自定义属性（.dark、[data-theme] 等）、SCSS 变量、Tailwind 配置值、shadcn HSL 三元组、基于应用自身主题估值的 Tailwind 工具类频率挖掘，以及频率提升的原始值——搭建包含令牌/排版/图标展示页面的设计系统包，将全新的 Storybook 工作坊接入应用真实的主题层和字体，深度提取组件以便通过 CSF3 story 脚手架移植，用确定性保真度评估门控结果，并在会话之间持久化移植进度。提取出的 tokens/tokens.json 可通过 figma_import_tokens 直接导入 Figma 变量——完成代码 → 设计系统 → Figma 的完整往返。同时修复了令牌格式化器引用 CSS 函数表达式（如 cubic-bezier(...)）的问题（被引用的缓动函数会悄悄破坏过渡效果——也影响 figma_export_tokens 的输出）。仅服务器端——无需重新导入插件。查看新内容 →

这是什么？

Figma Console MCP 将 AI 助手（如 Claude）连接到 Figma，实现：

• 🎨 设计系统提取 - 提取变量、组件和样式

• 🧬 代码库 → 设计系统提取 - 扫描生产代码库，将其事实上的样式挖掘为带逐令牌来源的 DTCG 令牌，搭建带 Storybook 工作坊的设计系统包，并用确定性保真度评估门控——然后将令牌往返同步到 Figma 变量（本地模式）

• 🔁 双向令牌同步 - 将 Figma 变量导出为 DTCG JSON（旧版或 2025.10 方言）+ 另外 9 种格式；将代码端的编辑完整应用推回 Figma——包括创建、重命名、别名重新定向以及受替换门控的删除。取代 Style Dictionary 和 Tokens Studio 的导出流水线。

• 📸 可视化调试 - 截图以获取上下文

• ✏️ 设计创建 - 直接在 Figma 中创建 UI 组件、画框和布局——包括通过变体轴矩阵一键创建组件集

• 🔧 变量管理 - 创建、更新、重命名和删除设计令牌

• 🕰 版本历史与时间序列感知 - 列出版本、比较快照差异、生成 markdown 变更日志、通过二分搜索 blame 追踪属性/变体的引入，并将每个组件的设计与 git 历史整合到生成的组件文档中

• ⚡ 实时监控 - 查看来自 Desktop Bridge 插件的控制台日志

• 📌 FigJam 看板 - 在协作看板上创建便签、流程图、表格和代码块

• 🎞️ 幻灯片演示 - 以编程方式构建和管理 Figma Slides 演示文稿

• ♿ 无障碍扫描 - 14 项 WCAG 设计检查，带合规级别标记、组件记分卡、axe-core 代码扫描、设计与代码一致性

• 📋 设计系统健康审计 - Lighthouse 风格的评分审计，涵盖命名、令牌、组件元数据、无障碍、一致性和覆盖率——可作为普通工具供任何 MCP 客户端使用（带逐项自动修复指引），也可作为可视化仪表盘应用

• 🛡 跨 MCP 身份标识 - 每个工具响应都携带 _mcp: "figma-console-mcp"，错误以 [figma-console-mcp] 为前缀，从而在运行多个 Figma MCP 的代理中保持归属明确

• ☁️ Cloud Write Relay - 网页 AI 客户端（Claude.ai、v0、Replit）可通过云配对在 Figma 中进行设计

• 🔄 四种连接方式 - 远程 SSE、云模式、NPX 或本地 Git

Related MCP server: MCP Figma

⚡ 快速开始

选择你的设置

首先，决定你想做什么：

⚠️ 重要提示：能力差异

关键结论： 远程 SSE 是只读的，提供 9 个工具。云模式让无需 Node.js 的网页 AI 客户端获得写入权限（101 个工具）。NPX/本地 Git 则提供完整的 121 个工具，并支持实时监控。

🚀 NPX 设置（推荐）

适用人群： 希望获得完整 AI 辅助设计能力的设计师。

你将得到： 全部 121 个工具，包括设计创建、变量管理和组件实例化。

前置条件

• Node.js 18+ — 通过 node --version 检查（下载）

• 已安装 Figma Desktop（不仅是网页应用）

• 一个 MCP 客户端（Claude Code、Cursor、Windsurf、Claude Desktop 等）

第 1 步：获取你的 Figma 令牌

1. 前往 Figma 帮助中的管理个人访问令牌

2. 按照步骤创建新的个人访问令牌

3. 输入描述：Figma Console MCP

4. 设置权限范围：文件内容（读取）、文件版本（读取）、变量（读取）、评论（读取和写入）

5. 复制令牌——你不会再看到它了！（以 figd_ 开头）

第 2 步：配置你的 MCP 客户端

Claude Code（CLI）：

claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest

Cursor / Windsurf / Claude Desktop：

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp@latest"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}

📂 在哪里找到你的配置文件

如果你不确定上面的 JSON 配置该放在哪里，以下是每个应用存储其 MCP 配置的位置：

给设计师的提示： ~ 符号表示你的主文件夹。在 macOS 上，它是 /Users/YourName/。在 Windows 上，它是 C:\Users\YourName\。你可以用任何文本编辑器打开这些文件——甚至 TextEdit 或记事本。

找不到文件？ 如果文件还不存在，就创建它。应用会在下次重启时读取。请确保整个文件是有效的 JSON（注意不要缺少逗号或括号）。

Claude Code 用户： 你完全可以跳过手动编辑。只需运行上面的 claude mcp add 命令，它会为你处理一切。

第 3 步：连接到 Figma Desktop

Desktop Bridge 插件：

1. 正常打开 Figma Desktop（无需特殊标志），然后打开一个文件

2. 前往 插件 → 开发 → 从 manifest 导入插件...

3. 选择 ~/.figma-console-mcp/plugin/manifest.json（稳定路径，由 MCP 服务器自动创建）

4. 在你的 Figma 文件中运行该插件——它会扫描 9223–9232 端口，并自动连接到正在运行的 MCP 服务器

关于插件更新的提醒。 Figma 在应用级别缓存插件文件（code.js 和 ui.html）。MCP 服务器会在每次启动时刷新 ~/.figma-console-mcp/plugin/ 下的文件，但 Figma 会一直使用其缓存副本，直到你重新导入 manifest。

仅当发布说明条目如此说明时，重新导入才是必需的——通常是在插件添加了服务器所需的新方法时（例如 v1.22.4、v1.10.0）。对于大多数升级，新服务器与之前的插件保持线上兼容，因此重新导入是可选的：你仍然会获得所有功能变更，只是没有插件端的装饰性改进（状态胶囊文案、pluginVersion 上报）。

当你确实需要重新导入时：插件 → 管理插件 → 重新导入 ~/.figma-console-mcp/plugin/manifest.json。稳定路径从不改变，所以这是一键操作。

第 4 步：重启你的 MCP 客户端

重启你的 MCP 客户端以加载新配置。

第 5 步：测试一下！

Check Figma status

→ 应显示连接状态，并带有活动的 WebSocket 传输

Create a simple frame with a blue background

→ 应在 Figma 中创建一个画框（确认具备写入权限！）

📖 完整设置指南

为贡献者准备：本地 Git 模式

适用人群： 希望修改源代码或为项目做贡献的开发者。

你将得到： 与 NPX 相同的 121 个工具，外加完整的源代码访问权限。

快速设置

# Clone and build
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
npm run build:local

配置你的 MCP 客户端

添加到你的配置文件（参见在哪里找到你的配置文件）：

{
  "mcpServers": {
    "figma-console": {
      "command": "node",
      "args": ["/absolute/path/to/figma-console-mcp/dist/local.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}

然后按照上面的 NPX 第 3-5 步 操作。

📖 完整设置指南

📡 远程 SSE（只读探索）

适用人群： 快速评估工具或进行只读设计数据提取。

功能： 9 个只读工具 — 查看数据、截图、读取日志、设计-代码一致性。无法创建或修改设计。

Claude Desktop（UI 方式）

1. 打开 Claude Desktop → 设置 → 连接器

2. 点击 “添加自定义连接器”

3. 输入：

   • 名称： Figma Console (Read-Only)

   • URL： https://figma-console-mcp.southleft.com/sse

4. 点击 “添加” — 完成！✅

当你首次使用设计系统工具时，OAuth 认证会自动完成。

Claude Code

⚠️ 已知问题： Claude Code 原生的 --transport sse 存在一个 缺陷。请改用 mcp-remote：

claude mcp add figma-console -s user -- npx -y mcp-remote@latest https://figma-console-mcp.southleft.com/sse

💡 提示： 如需完整功能，请使用 NPX 设置 而不是远程 SSE。

其他客户端（Cursor、Windsurf 等）

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://figma-console-mcp.southleft.com/sse"]
    }
  }
}

升级到完整功能

准备好创建设计了吗？请按照上面的 NPX 设置 指南操作；如果你不想安装 Node.js，可以尝试 云模式。

📖 完整设置指南

☁️ 云模式（Web AI 客户端）

适用场景： 使用 Claude.ai、v0、Replit 或 Lovable 创建和修改 Figma 设计 — 无需 Node.js。

功能： 101 个工具，包括完整写入权限 — 设计创建、变量管理、组件实例化，以及所有 REST API 工具。只有实时监控（控制台日志、选区跟踪、文档变更）需要本地模式。

前提条件

• Figma 个人访问令牌 — 在此创建（以 figd_ 开头）

• Figma Desktop 并安装 Desktop Bridge 插件（参见 Desktop Bridge 设置）

• 支持 MCP 的 Web AI 客户端（Claude.ai、Lovable、v0、Replit 等）

第 1 步：添加 MCP 连接器

将此端点添加到你的 AI 平台的 MCP 设置中：

URL： https://figma-console-mcp.southleft.com/mcp 身份验证： 以你的 Figma PAT 作为 Bearer token

在 Claude.ai 中：设置 → 连接器 → 添加自定义连接器 → 粘贴上面的 URL。 在 Lovable/v0/Replit 中：在设置中查找“添加 MCP 服务器”或“集成”→ 粘贴 URL 并添加你的 token。

第 2 步：配对插件

1. 在 Figma Desktop 中打开 Desktop Bridge 插件（插件 → 开发 → Figma Desktop Bridge）

2. 告诉你的 AI 助手：

Connect to my Figma plugin

3. AI 会给你一个 6 位配对代码（5 分钟内有效）

4. 在插件中： 开启“云模式”→ 输入代码 → 点击连接

5. 配对成功！ 现在可以使用完整写入权限了。

你可以做什么

配对后，即可使用自然语言进行设计：

Create a card component with a header image, title, description, and action button
Set up a color token collection with Light and Dark modes
Add a "High Contrast" mode to my existing token collection

工作原理

你的 AI 客户端通过云 MCP 服务器发送写入命令，服务器通过 WebSocket 将命令中继到你 Figma Desktop 中运行的 Desktop Bridge 插件。插件使用 Figma Plugin API 执行命令，并通过同一路径返回结果。

AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugin → Figma

任何套餐都支持变量： 云模式使用 Plugin API（而不是 Enterprise REST API），因此变量管理在 Free、Pro 和 Organization 套餐上均可正常使用。

📖 完整设置指南

📊 安装方式对比

关键要点： 远程 SSE 是只读的。云模式为无需 Node.js 的 Web AI 客户端增加了写权限。NPX/本地 Git 提供完整的 121 个工具。

📖 完整功能对比

🎯 测试你的连接

设置完成后，试试以下提示词：

基础测试（所有模式）：

Navigate to https://www.figma.com and check status

设计系统测试（需要身份验证）：

Get design variables from [your Figma file URL]

云模式测试：

Connect to my Figma plugin

→ 按配对流程操作，然后尝试：“创建一个简单的蓝色矩形”

插件测试（仅限本地模式）：

Show me the primary font for [your theme name]

🔐 身份验证

远程模式 - OAuth（自动）

当你首次使用设计系统工具时：

1. 浏览器会自动打开 Figma 授权页面

2. 点击“允许”进行授权（一次性）

3. Token 会被安全存储并自动刷新

4. 适用于 Figma 的 Free、Pro 和 Enterprise 套餐

本地模式 - 个人访问令牌（手动）

1. 访问 https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens

2. 生成具有以下作用域的 token：文件内容（读取）、文件版本（读取）、变量（读取）、评论（读取和写入）

3. 将 FIGMA_ACCESS_TOKEN 环境变量添加到 MCP 配置中

🛠️ 可用工具

状态与诊断

• figma_get_status - 检查 WebSocket 桥接连接和文件上下文

• figma_diagnose - 面向设计师的可读健康检查 + 设置指导

• figma_reconnect - 强制重新连接到 Desktop Bridge 插件

• figma_navigate - 在已连接的插件间切换活动文件目标（本地），或导航云端无头浏览器（远程/云）

控制台调试

• figma_get_console_logs - 检索控制台日志

• figma_watch_console - 实时日志流

• figma_clear_console - 清除日志缓冲区

• figma_reload_plugin - 重新加载当前页面

可视化调试

• figma_take_screenshot - 捕获 UI 截图

设计系统提取

• figma_get_design_system_kit - 一次调用获取完整设计系统 — tokens、组件、样式、视觉规范

• figma_get_variables - 提取设计 token/变量

• figma_get_component - 获取组件数据（元数据或重建规范）

• figma_get_component_for_development - 组件 + 图片

• figma_get_component_image - 仅图片

• figma_get_styles - 颜色、文本、效果样式

• figma_get_file_data - 完整文件结构

• figma_get_file_for_plugin - 优化后的文件数据

• figma_audit_design_system_report - 面向任何 MCP 客户端的评分健康审计 — 六类报告（命名、tokens、元数据、可访问性、一致性、覆盖率），逐项附带修复建议（“这个 MCP 能修复吗？”），按类别分块下钻，实时优先的数据并注明来源，5 分钟缓存

📚 共享库检查

• figma_get_library_component_by_key - 将任意组件 key 解析为完整属性 + 变体 + 视觉规范 — 无需源库文件的 URL。适用于 COMPONENT_SET 和独立 COMPONENT 键。超过 500KB 时自适应压缩。

• figma_get_library_components - 发现库文件中的所有组件（需要库文件 URL/key）

• figma_get_library_variables - 列出当前文件已订阅的团队库中的所有变量。适用于所有 Figma 套餐 — 使用 Plugin API 路径，而非仅限 Enterprise 的 REST 端点。可按 libraryName、collectionName 或 resolvedType 过滤。

• figma_import_library_variable - 将库变量导入当前文件。返回一个本地 id，可直接传给 figma_set_fills / figma_update_variable / 任何变量绑定工具。

☁️ 云中继

• figma_pair_plugin - 生成配对代码，通过云中继连接 Desktop Bridge 插件。

✏️ 设计创建（本地模式 + 云模式）

• figma_execute - 强大工具：运行任意 Figma Plugin API 代码来创建设计

  • 创建 frame、形状、文本、组件

  • 应用自动布局、样式、效果

  • 以编程方式构建完整的 UI 原型

  • 可选的 fileKey 可直接指定某个已连接的文件（仅限本地模式），无需触碰活动文件或目标锁

• figma_execute_across_files - 仅限本地模式。 在多个已连接 Desktop Bridge 的文件中同时并发运行同一脚本，返回按文件划分的结果映射 — 用于跨文件设计系统的一致性检查和修复，替代“打开文件、运行插件、逐个文件重复”的流程

  • 使用 fileKeys（来自 figma_list_open_files）指定文件，或传入 allFiles: true 以覆盖所有已连接的文件 — 两者必选其一，这样脚本永远不会扩散到你本不想操作的文件

  • 每个文件独立超时和错误隔离：某个文件缓慢或失败不会阻塞或拖垮其他文件

• figma_create_component_set - 通过一次声明式调用创建包含变体的组件集

  • 基于基础组件，从轴矩阵生成所有变体组合（例如 { State: ["default", "hover", "disabled"], Size: ["sm", "lg"] } → 6 个变体），或组合现有组件

  • 使用 Prop=Value 变体命名，底层使用 combineAsVariants，可选自动排列的带标签网格

  • 返回每个变体的 key，可直接用于 figma_instantiate_component

• figma_arrange_component_set - 将变体整理为专业的组件集

  • 将多个组件变体转换为规范的 Figma 组件集

  • 自动应用原生紫色虚线边框可视化

  • 创建包含标题、行标签和列标题的白色容器 frame

  • 行标签与每个网格行垂直居中

  • 列标题与每个列水平居中

  • 使用自然语言，例如“arrange these variants”或“organize as component set”

• figma_set_description - 为组件添加丰富的描述文档

  • 为组件、组件集和样式添加描述

  • 支持 Markdown 格式，便于编写丰富文档

  • 描述会显示在面向开发者的 Dev Mode 中

🧩 Figma Slots（本地模式 + 云模式）

• figma_create_slot - 通过正式版 createSlot() API 为组件添加 slot — 会自动创建关联的 SLOT 属性；适用于独立组件和组件集内的变体

• figma_get_slots - 列出组件、组件集（跨变体聚合）或实例上的 slots — id、名称、属性 key、尺寸和当前子节点

• figma_append_to_slot - 填充实例的 slot，通过克隆现有节点或创建新内容（setProperties 按设计会拒绝 slot 值 — 这才是填充路径）

• figma_reset_slot - 清除实例上某个 slot 的内容

• figma_add_slot_property - 通过手动绑定 SLOT 属性，将现有 frame 改造为 slot，支持 description 和 preferredValues

🔍 设计与代码一致性（所有模式）

• figma_check_design_parity - 将 Figma 组件规格与代码实现进行比较，生成带评分的差异报告及可操作的修复项

• figma_generate_component_doc - 通过合并 Figma 设计数据与代码侧信息，生成与平台无关的 Markdown 文档

🔁 令牌同步（本地模式 + 云模式）

• figma_export_tokens - 将 Figma 变量导出为代码库中的设计令牌文件。 标准 DTCG JSON（默认使用 legacy hex 方言，或通过 dtcgDialect: "2025" 使用 DTCG 2025.10 对象颜色/尺寸）以及 CSS、Tailwind v4/v3、SCSS、TS、JSON、Style Dictionary 和 Tokens Studio 格式。针对现有源文件进行差异感知合并（仅写入更改部分）。tokens.config.json 自动发现意味着首次设置后可零参数调用。Scopes 和 codeSyntax 元数据通过 $extensions 往返保留。替代 Style Dictionary 和 Tokens Studio 对常用样式方法的导出管道。

• figma_import_tokens - 将代码侧令牌编辑推回 Figma，并带有完整的应用阶段。 与当前 Figma 状态进行差异比较，然后应用值更新、创建缺失的集合/变量、应用重命名、写入真实的别名 (VARIABLE_ALIAS) 引用，并且——仅在 strategy: "replace" 下——删除仅存在于 Figma 的变量。往返安全——Figma 变量 ID 保存在 DTCG $extensions["figma-console-mcp"] 中，因此任一侧的重命名都不会产生重复。接受两种 DTCG 方言。支持 dry-run 策略以安全预览。在云模式中，通过 payload 或 files 内联传入令牌（无法访问本地文件系统）。

🧬 设计系统提取（仅限本地模式）

将生产代码库转变为设计系统：分析 → 提取令牌 → 搭建脚手架 → 移植组件 → 验证。仅限本地模式——这些工具会读写你的本地文件系统，因此它们永远不会在云模式中注册。

• figma_ds_analyze - 扫描一个或多个生产应用代码库——框架/样式/供应商层检测；按使用量排序的组件清单，分类为 vendored / wrapped / pure-vendor / bespoke，包含 prop 契约、从真实调用点推断变体、重复检测；图标 + 排版捕获；以及架构分类（原子级别、类似 FollowButton → Button 的特化、缺失的通用原语——即“UI 工具包 vs 设计系统”分析）

• figma_ds_extract_tokens - 挖掘应用的样式并将其转化为 DTCG 令牌。 首先识别声明的意图——多模式 CSS 自定义属性（.dark / [data-theme] 及其他约定）、SCSS 变量、Tailwind 配置值、shadcn HSL 三元组——再加上根据应用自身主题进行价值评估的 Tailwind 工具类频率挖掘，以及通过频率提升的重复原始值。每个令牌都在 $extensions 中携带来源信息（源文件 file:line、置信度、频率）；输出可通过 figma_import_tokens 直接导入 Figma 变量

• figma_ds_scaffold - 生成设计系统包——包骨架、通过共享格式化引擎生成的令牌文件、令牌/排版/图标展示文档页、框架对等依赖，以及工作流 README

• figma_ds_setup_storybook - 将新初始化的 Storybook 工作坊连接到提取结果——一个预览样式表，携带源应用的 @theme 映射、自定义 @utility 定义、@layer base 和 @font-face 规则；自托管字体复制；配置补丁（Tailwind vite 插件、自动 JSX 运行时）；以及基于提取模式构建的主题工具栏

• figma_ds_extract_component - 深度提取一个组件以供移植——源码、prop 契约、观察到的调用点变体、样式触点，以及一个可随时适配的 CSF3 story 脚手架

• figma_ds_verify - 确定性保真度评估——DTCG 解析 + 别名完整性、带引号的 CSS 表达式扫描、工作坊 var() 解析、结构 + 移植覆盖率，以及 Figma 往返就绪状态

• figma_ds_status - 读取或记录移植进度，并在会话之间持久化

🔧 变量管理（本地模式 + 云模式）

• figma_create_variable_collection - 创建带有模式的新变量集合

• figma_create_variable - 创建 COLOR、FLOAT、STRING 或 BOOLEAN 变量

• figma_update_variable - 更新特定模式中的变量值

• figma_rename_variable - 重命名变量并保留其值

• figma_delete_variable - 删除变量

• figma_delete_variable_collection - 删除集合及其所有变量

• figma_add_mode - 向集合添加模式（例如“Dark”、“Mobile”）

• figma_rename_mode - 重命名现有模式

• figma_batch_create_variables - 一次调用创建最多 100 个变量（快 10-50 倍）

• figma_batch_update_variables - 一次调用更新最多 100 个变量值

• figma_setup_design_tokens - 以原子方式创建完整的令牌系统（集合 + 模式 + 变量）——值接受 DTCG 花括号引用（"{color.blue.600}"），这些引用会解析为真实的变量别名

📌 FigJam 白板工具（本地模式 + 云模式）

• figjam_create_sticky - 创建带有颜色选项的便签

• figjam_create_stickies - 批量创建最多 200 个便签

• figjam_create_connector - 使用带标签的连接线连接节点

• figjam_create_shape_with_text - 创建流程图形状（菱形、椭圆等）

• figjam_create_table - 创建包含单元格数据的表格

• figjam_create_code_block - 添加带语法高亮的代码片段

• figjam_auto_arrange - 以网格、水平或垂直布局排列节点

• figjam_get_board_contents - 读取 FigJam 白板中的所有内容

• figjam_get_connections - 读取连接图（流程图、关系）

🎞️ 幻灯片演示工具（本地模式 + 云模式）

• figma_list_slides - 列出所有幻灯片及其 ID、位置和跳过状态

• figma_get_slide_content - 获取幻灯片的完整内容树

• figma_get_slide_grid - 获取演示文稿的 2D 网格布局

• figma_get_slide_transition - 读取幻灯片的过渡设置

• figma_get_focused_slide - 获取当前聚焦的幻灯片

• figma_create_slide - 创建新的空白幻灯片

• figma_delete_slide - 从演示文稿中删除幻灯片

• figma_duplicate_slide - 克隆现有幻灯片

• figma_reorder_slides - 通过新的 2D 网格布局重新排序幻灯片

• figma_set_slide_transition - 设置过渡效果（22 种样式、8 种曲线）

• figma_skip_slide - 切换幻灯片在演示模式中是否被跳过

• figma_add_text_to_slide - 向幻灯片添加文本，支持自定义字体、颜色、对齐和换行

• figma_add_shape_to_slide - 添加带有颜色的矩形或椭圆形状

• figma_set_slide_background - 设置幻灯片的背景色（创建或更新）

• figma_get_text_styles - 获取所有本地文本样式及其 ID、字体和字号

• figma_set_slides_view_mode - 切换网格视图与单张幻灯片视图

• figma_focus_slide - 导航到特定幻灯片

📖 详细工具文档

📖 示例提示

云模式（Web AI 客户端）

Connect to my Figma plugin so we can start designing
Pair with my Figma file and create a login form with email, password, and submit button
Set up a brand color token collection with Light and Dark modes

插件调试

Navigate to my Figma plugin and show me any console errors
Watch the console for 30 seconds while I test my plugin
Get the last 20 console logs

设计系统提取

Get all design variables from https://figma.com/design/abc123
Extract color styles and show me the CSS exports
Get the Button component with a visual reference image
Get the Badge component in reconstruction format for programmatic creation

设计创建（本地模式 + 云模式）

Create a success notification card with a checkmark icon and message
Design a button component with hover and disabled states
Build a navigation bar with logo, menu items, and user avatar
Create a modal dialog with header, content area, and action buttons
Arrange these button variants into a component set
Organize my icon variants as a proper component set with the purple border

变量管理（本地模式 + 云模式）

Create a new color collection called "Brand Colors" with Light and Dark modes
Add a primary color variable with value #3B82F6 for Light and #60A5FA for Dark
Rename the "Default" mode to "Light Theme"
Add a "High Contrast" mode to the existing collection

设计与代码一致性

Compare the Button component in Figma against our React implementation
Check design parity for the Card component before sign-off
Generate component documentation for the Dialog from our design system

FigJam 白板

Create a retrospective board with "Went Well", "To Improve", and "Action Items" columns
Build a user flow diagram for the checkout process with decision points
Read this brainstorming board and summarize the key themes
Generate an affinity map from these meeting notes
Create a comparison table of our three platform options

幻灯片演示

List all slides and tell me which ones are skipped
Add a new slide with the title "Thank You" in 72px text
Set a DISSOLVE transition on the first slide with 0.5 second duration
Duplicate slide 5 for an A/B comparison
Skip slides 8 and 9 — they're not ready for the client presentation
Reorder my slides so the conclusion comes before Q&A

可视化调试

Take a screenshot of the current Figma canvas
Navigate to this file and capture what's on screen

📖 更多使用场景与示例

🎨 AI 辅助设计创建

需要 Desktop Bridge： 此功能适用于本地模式（NPX 或本地 Git）和云模式。未配对云模式的远程 SSE 为只读，无法创建或修改设计。

此 MCP 服务器最强大的能力之一，是能够与任何兼容 MCP 的 AI 助手（如 Claude Desktop 或 Claude Code）通过自然语言对话，直接在 Figma 中设计完整的 UI 组件和页面。

可以做什么

从零开始创建原创设计：

Design a login card with email and password fields, a "Forgot password?" link,
and a primary Sign In button. Use 32px padding, 16px border radius, and subtle shadow.

利用现有组件库：

Build a dashboard header using the Avatar component for the user profile,
Button components for actions, and Badge components for notifications.

生成完整的页面布局：

Create a settings page with a sidebar navigation, a main content area with form fields,
and a sticky footer with Save and Cancel buttons.

工作原理

1. 你用日常英语描述你想要的

2. AI 搜索你的组件库，使用 figma_search_components 查找相关构建块

3. 通过 figma_instantiate_component 实例化组件，并带有正确的变体和属性

4. 通过 figma_execute 使用完整的 Figma 插件 API 创建自定义元素

5. 视觉验证自动捕获截图并迭代，直到设计看起来正确

受益者

示例工作流

全新设计：

“创建一个通知提示条，左侧带图标、标题和描述文本，以及一个关闭按钮。使用我们的品牌色。”

AI 会创建自定义画框，应用你的设计令牌，并从零开始构建该组件。

组件组合：

“使用 Avatar 组件（大尺寸）、两个 Button 组件（Edit Profile 和 Settings）以及一个用于显示用户状态的 Badge 来构建用户资料卡。”

AI 会搜索你的组件库，找到确切的组件，并以正确的间距和对齐方式组装它们。

设计迭代：

“间距感觉太紧了。将各部分之间的间距增加到 24px，并让标题更大。”

AI 会修改现有设计，截取屏幕截图进行验证，并持续迭代直到你满意。

视觉验证

AI 在创建设计后会自动遵循验证工作流：

1. 创建 → 执行设计代码

2. 截图 → 捕获结果

3. 分析 → 检查对齐、间距和视觉平衡

4. 迭代 → 修复检测到的任何问题

5. 验证 → 最终截图确认

这确保设计不仅在技术上正确——它们看起来也正确。

🎨 Desktop Bridge 插件（推荐连接）

Figma Desktop Bridge 插件是连接 Figma 与 MCP 服务器的推荐方式。它通过 WebSocket 通信——无需特殊的 Figma 启动标志，并且在 Figma 重启后依然保持连接。

设置

1. 打开 Figma Desktop（正常启动——无需调试标志）

2. 转到 Plugins → Development → Import plugin from manifest...

3. 从 figma-console-mcp 目录中选择 figma-desktop-bridge/manifest.json

4. 在你的 Figma 文件中运行该插件——它会通过 WebSocket 自动连接（扫描端口 9223–9232）

5. 询问你的 AI：“检查 Figma 状态”以验证连接

一次性导入。 导入后，该插件会保留在你的开发插件列表中。每当你想要使用 MCP 时，运行它即可。

📖 Desktop Bridge 文档

功能

读取操作：

• 无需 Enterprise API 即可读取变量

• 可靠的组件描述（绕过 API bug）

• 多模式支持（Light/Dark/Brand 变体）

• 实时选区跟踪和文档更改监控

写入操作：

• 设计创建 - 通过 figma_execute 创建画框、形状、文本和组件

• 变量管理 - 对变量和集合的完整 CRUD 操作

• 模式管理 - 添加和重命名模式以支持多主题

传输的工作原理

• MCP 服务器通过 Desktop Bridge 插件以 WebSocket 进行通信

• 服务器首先尝试端口 9223，如果需要，会自动依次回退到端口 9224–9232

• 插件会扫描该范围内的所有端口，并连接到它找到的每一个活动服务器

• 所有 121 个工具都通过 WebSocket 传输工作

多个文件： WebSocket 服务器支持多个并发的插件连接——每个打开的 Figma 文件一个连接。每个连接通过文件 key 进行跟踪，并具有独立的状态（选区、文档更改、控制台日志）。

环境变量：

• FIGMA_WS_PORT — 覆盖首选的 WebSocket 端口（默认值：9223）。如果首选端口被占用，服务器将从该值开始在一个 10 端口范围内依次回退。

• FIGMA_WS_HOST — 覆盖 WebSocket 服务器的绑定地址（默认值：localhost）。在 Docker 内运行时设置为 0.0.0.0，以便宿主机能够访问 MCP 服务器。

Cloud Mode： 插件还支持一个 Cloud Mode 开关，用于与 Web AI 客户端（Claude.ai、v0、Replit、Lovable）配对。在插件 UI 中切换 "Cloud Mode"，输入你的 AI 助手提供的 6 位配对代码，然后点击连接。详见 Cloud Mode。

插件限制： 在 Local Mode 下，可与 NPX 或本地 Git 配合使用。在 Cloud Mode 下，与远程 MCP 端点配对。未经 Cloud Mode 配对的远程 SSE 为只读。

🔀 多实例支持（v1.10.0）

Figma Console MCP 现在支持多个同时运行的实例——非常适合需要跨多个项目工作，或同时使用 Claude Desktop 的 Chat 和 Code 标签页的设计师和开发者。

问题（v1.10.0 之前）

当两个进程尝试启动 MCP 服务器时（例如 Claude Desktop 的 Chat 标签页和 Code 标签页），第二个进程会因 EADDRINUSE 崩溃，因为两者都会争夺端口 9223。

现在的工作原理

• 服务器首先尝试使用端口 9223（默认端口）

• 如果该端口已被占用，它会自动尝试 9224、9225，一直到 9232

• Figma 中的 Desktop Bridge 插件会同时连接到所有活动服务器

• 每个服务器实例都会接收实时事件（选区变化、文档更改、控制台日志）

• figma_get_status 会显示你当前使用的端口，并列出其他活动实例

这对你意味着什么

我需要做什么吗？

什么都不用做。 多实例支持完全是自动的：

• 每个 MCP 服务器会占用范围内下一个可用端口

• Desktop Bridge 插件会扫描所有端口，并连接到每个活动服务器

• 已关闭标签页留下的孤立进程会在启动时自动清理

• 无需手动管理端口——插件已经会扫描整个端口范围

（仅当插件代码本身发生变化时才需要重新导入 manifest——例如在包更新之后。端口范围扫描已在随附的插件中内置。）

🧩 MCP Apps（实验性）

Figma Console MCP 包含对 MCP Apps 的支持——一种丰富的交互式 UI 体验，可直接在任何支持 MCP Apps 协议扩展 的 MCP 客户端内渲染。它基于官方 @modelcontextprotocol/ext-apps SDK 构建。

什么是 MCP Apps？ 传统的 MCP 工具向 AI 返回文本或图像。MCP Apps 更进一步——它们在聊天中内联渲染交互式 HTML 界面，让用户无需消耗 AI 上下文即可直接浏览、筛选并与数据交互。

Token Browser

一个交互式设计 token 浏览器。

用法： 在连接到 Figma 文件时，让 Claude "浏览设计 token"或"显示设计 token"。

功能：

• 按集合浏览所有 token，并带有可展开的分区

• 按类型（颜色、数字、字符串）筛选，并按名称/描述搜索

• 每个集合的模式列（浅色、深色、自定义）与 Figma 的 Variables 面板一致

• 颜色样本、别名解析，以及任意值的点击复制

• 通过 Desktop Bridge（本地模式）无需 Enterprise 计划即可使用

Design System Dashboard

一个 Lighthouse 风格的健康评分卡，可从六个类别审计你的设计系统。

用法： 在连接到 Figma 文件时，让 Claude "审计设计系统"或"显示设计系统健康状况"。

功能：

• 总体加权得分（0–100），带有六个类别的仪表：命名、Token、组件、可访问性、一致性、覆盖率

• 可展开的类别分区，包含单独发现、严重性指示器和可操作详情

• 诊断位置将发现链接到特定的变量、组件或集合

• 提示框说明每项检查的目的和评分标准

• 刷新按钮可重新运行审计，而不会消耗 AI 上下文

• 纯评分引擎，无外部依赖——所有分析均在本地运行

不支持 MCP Apps？同样的审计，纯工具版本： figma_audit_design_system_report 运行完全相同的评分引擎，并将报告作为数据返回——默认返回摘要，通过 category 按类别下钻，通过 format: "full" 返回完整 JSON——同时附带修复建议部分，说明哪些发现本 MCP 可以修复（design）、哪些需要先做设计决策（design-assisted）、哪些需要人工设计工作（manual）。它在每个 MCP 客户端中都能使用，无需 ENABLE_MCP_APPS 标志；结果会缓存 5 分钟（用 forceRefresh 可重新抓取）。

启用 MCP Apps

MCP Apps 默认已在上面的配置中启用（通过 "ENABLE_MCP_APPS": "true"）。如果你是在 v1.10.0 之前配置的，并且配置中没有这一项，请将其添加到你的 env 配置段中：

"env": {
  "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
  "ENABLE_MCP_APPS": "true"
}

注意： MCP Apps 需要支持 ext-apps 协议 的 MCP 客户端（例如 Claude Desktop）。此功能为实验性功能，协议可能会演进。

未来的 MCP Apps 路线图

计划中的 MCP Apps：

• Component Gallery — 用于搜索和预览组件的可视化浏览器，支持变体探索

• Style Inspector — 用于探索颜色、文本和效果样式的交互式面板，带有实时预览

• Variable Diff Viewer — 跨模式和集合并排比较 token 值

• 该架构支持以最少的样板代码添加新应用——每个应用都是自包含模块，拥有自己的服务端工具注册和客户端 UI。

🚀 高级主题

• 安装指南 - 适用于所有 MCP 客户端的完整安装指南

• 自托管 - 在 Cloudflare 上部署你自己的实例

• 架构 - 底层工作原理

• OAuth 设置 - 为自托管部署配置 OAuth

• 故障排查 - 常见问题及解决方案

🤝 对比 Figma 官方 MCP

Figma Console MCP（本项目） - 调试、数据提取和设计创建

• ✅ 来自 Figma 插件的实时控制台日志

• ✅ 截图捕获和可视化调试

• ✅ 错误堆栈跟踪和运行时监控

• ✅ 原始设计数据提取（JSON）

• ✅ FigJam 看板的创建和读取（便签、流程图、表格）

• ✅ 支持远程或本地使用

Figma 官方 Dev Mode MCP - 代码生成

• ✅ 从设计生成 React/HTML 代码

• ✅ Tailwind/CSS 类生成

• ✅ 组件样板脚手架

将两者结合使用以获得完整工作流：用官方 MCP 生成代码，然后用 Console MCP 进行调试和数据提取。

🛤️ 路线图

当前状态： v1.40.0（稳定版）——生产就绪。最新功能：从生产代码库提取设计系统——七个本地模式 figma_ds_* 工具，可扫描一个或多个应用（框架/样式/供应商检测、按使用频率排序的组件清单（分类为 vendored/wrapped/pure-vendor/bespoke）、从真实调用点推断变体、重复检测，以及一项架构分析，将 UI 套件特化与缺失的通用原语区分开来），将实际使用的样式挖掘为带逐令牌溯源信息的 DTCG 令牌（多模式 CSS 自定义属性、SCSS、Tailwind config、shadcn HSL 三元组、基于应用自身主题估值的工具类频率挖掘），搭建带有展示文档页的设计系统包，将全新的 Storybook 工作台接入应用的真实主题层和字体，深度提取组件并附带 CSF3 故事脚手架以便移植，通过确定性保真度评估进行验证，并在会话之间持久化移植进度——提取的令牌可通过 figma_import_tokens 直接导入 Figma 变量。在 v1.39.1 对永远无法清除的插件更新横幅的修复之上——较旧的服务器实例不断催促较新的插件重新导入，而重新导入只会安装相同或更新的插件。在 v1.39.0 的多文件执行之上——figma_execute_across_files 可针对多个已连接 Desktop Bridge 的文件并发运行一个脚本（四个文件 x 2 秒的工作量约 3 秒完成，而非约 8 秒），并且 figma_execute 接受可选的 fileKey 参数，以在不移动活动文件或释放目标锁的情况下针对单个文件；目标必须显式指定（fileKeys 或 allFiles: true），因此不会波及你未指定的文件。来自社区 PR #107，作者 @Wolfr。附带一个中继修复：插件 ui.html 中的 handleResult() 逐字段重建每个响应字段，并静默丢弃了 resultAnalysis 和 fileContext，因此 figma_execute 自身描述中要求调用方执行的 resultAnalysis.warning 检查从未成为可能（重新导入 manifest.json 以获取这两个字段；其余功能无需即可正常工作）。在 v1.38.2 的连接稳定性修复之上——服务器自身的孤儿回收器会终止健康的 MCP 服务器，因为其存活探针使用了 IPv4 字面量，而服务器绑定的是 IPv6 回环地址，这使得所有终止安全门都形同虚设；这正是所有 MCP 客户端反复出现 “Server disconnected” 错误的根源。同时，v1.38.1 修复了共享库变量工具——自 v1.29.0 起，这些工具一直静默报告零个集合，并将失败的导入报告为成功。在 v1.38.0 生成文档中的持续组件变更日志之上——figma_generate_component_doc 接受一个可选的 history 参数，该参数从 Figma 版本历史中提取每个组件的设计历史（每个版本与组件范围进行差异对比，因此重命名、新增属性和令牌绑定会以行形式显示），同时从组件源文件上的 git log 提取代码历史，并以 ## History 部分呈现，包含设计、代码和发布说明表格。优先使用带标签的版本，当文件没有标签版本时回退到自动保存；默认关闭，因此现有调用不受影响（仅服务器端，无需重新导入插件）。在 v1.37.x 的面向每个客户端的设计系统健康审计之上——figma_audit_design_system_report 运行仪表盘的确定性六类评分引擎，并将报告作为数据返回，包含逐条发现项的修复建议、实时优先且经 fileKey 验证的数据（披露来源）、按类别分块下钻，以及 5 分钟缓存（仅服务器端，无需重新导入插件）。在 v1.36.0 的多文件并行工作目标锁之上—— —— figma_navigate 接受一个 lock: true 标志，用于固定活动文件，使 AI 智能体可以在一个文件中工作，而你在另一个文件中工作，而不会将命令路由到错误的文件。在 v1.35.0 的 Figma Slots 写入支持之上——通过 5 个新工具（figma_create_slot、figma_get_slots、figma_append_to_slot、figma_reset_slot、figma_add_slot_property）创建、检查、填充和重置 Slots（Config 2026 上 GA），这些工具已针对 GA Plugin API 进行实时验证，并基于社区 PR #77。在 v1.34.0 的双向令牌同步 v2 + DTCG 2025.10 之上——figma_import_tokens 应用完整的差异计划（创建缺失的集合/变量、应用重命名、写入真实的 VARIABLE_ALIAS 引用，并且仅在显式 replace 下删除），figma_export_tokens 可按请求使用 DTCG 2025.10 方言（旧版默认逐字节一致），变量作用域/codeSyntax 通过 $extensions 往返，figma_setup_design_tokens 通过 DTCG 花括号引用接受别名值，figma_create_component_set 一次调用即可从轴矩阵构建完整的变体集。在 v1.33.x 系列之上：版本握手修复（仅当插件文件实际更改时才触发重新导入横幅）、安全依赖清理，以及 v1.33.0 的连接 UX 全面改进（基于实时连接状态的真实状态胶囊、带自愈重连的 /health 自动发现）+ 一次包含 33 项修复的全代码库审计（无损 DTCG 多模式往返、跨集合别名解析、各 REST 工具的分支 URL 正确性、缓存投毒与 CSWSH 修复、桥接优先截图）。构建在以下基础之上：符合 WCAG 的无障碍审计（低于 1.5× 的行高不再被误报为失败；可读性提示与一致性检查解耦，并限定于多行文本；代码侧 WCAG 1.4.12 检查）、自愈的 Desktop Bridge 连接（僵尸进程回收器 + 自动重连看门狗——修复了反复出现的 “not connected until restart” 错误）、写入工具中原生的填充/描边变量绑定 + 排版控制、共享库检查（基于 key 的组件解析 + 无需 Enterprise 计划即可读取/导入库变量）、10 格式令牌导出管道（DTCG、CSS、Tailwind v4、Tailwind v3、SCSS、TS module、JSON flat/nested、Style Dictionary v3、Tokens Studio）、双向 Figma↔code 令牌同步、版本历史与时间序列感知、FigJam + Slides 支持、Cloud Write Relay、Design System Kit、仅 WebSocket 连接、智能多文件跟踪、121 个工具（本地）/ 101 个工具（云端）/ 9 个工具（远程只读）、Comments API、跨 MCP 身份消歧，以及 MCP Apps。

近期版本：

• v1.40.0 - 设计系统提取。七个仅本地模式的新工具，可将生产代码库转化为设计系统，外加配套的提取引擎。figma_ds_analyze 扫描一个或多个应用代码库：框架/样式/供应商层检测（React/Next/Angular/Web Components；Tailwind v3/v4、CSS Modules、SCSS、Emotion、styled-components；shadcn/ui、Radix、MUI、Chakra…），按使用频率排序的组件清单，按 vendored/wrapped/pure-vendor/bespoke 分类并附带 prop 契约，从真实调用点推断变体，重复检测，图标与字体捕获，以及将 UI kit 与设计系统区分开的架构分类（原子层级、FollowButton → Button 这类特化、缺失的通用原语）。figma_ds_extract_tokens 将事实上的样式挖掘为 DTCG 令牌——跨 .dark/[data-theme] 约定的多模式 CSS 自定义属性、SCSS 变量、Tailwind 配置值、shadcn HSL 三元组、基于应用自身主题估值的 Tailwind 工具类频率挖掘、频率提升的原始值——并在 $extensions 中记录每个令牌的来源，可通过 figma_import_tokens 直接导入 Figma 变量。figma_ds_scaffold 生成包（通过共享格式化器生成令牌文件，以及令牌/字体/图标展示页）；figma_ds_setup_storybook 将全新的 Storybook 工作台接入应用真实的主题层和字体；figma_ds_extract_component 生成带 CSF3 story 脚手架的单组件移植清单；figma_ds_verify 用确定性保真度评估外加 Figma 往返就绪性把关结果；figma_ds_status 跨会话持久化移植进度。另修复了 CSS/SCSS/Tailwind v4 格式化器对 CSS 函数表达式加引号的问题（被引号的 cubic-bezier(...) 会悄悄杀死过渡——也影响 figma_export_tokens）。仅服务端，无需重新导入插件。

• v1.39.1 - 插件更新横幅永远无法清除。computePluginUpdateAvailable() 只是一个没有方向检查的简单不等式，因此当服务器捆绑的插件副本比已连接的插件更旧时，仍会提示用户重新导入——而重新导入只会安装相同或更新的插件。这不是边缘情况：9223–9232 端口范围会让多个服务器实例同时存活，BUNDLED_PLUGIN_VERSION 仅在模块加载时解析一次，而升级前仍在运行的每个服务器都会对已正确更新的插件发出提示。已用四个残留的 v1.38.2 服务器对刚重新导入的 1.39.0 插件进行了实况复现。现在仅在捆绑副本确实更新时才标记。仅服务端，无需重新导入插件。1452 个测试。

• v1.39.0 - 多文件执行。新的 figma_execute_across_files 可针对多个已连接 Desktop Bridge 的文件并发运行同一脚本，具备按文件的错误隔离和独立超时（实况验证：四个文件 × 各 2 秒的工作在约 3.0 秒内完成，所有派发均在 5ms 内——而串行需要约 8 秒）。figma_execute 新增可选参数 fileKey，用于定位单个非活动文件，而不移动活动文件或释放目标锁。目标指定刻意保持显式——fileKeys 或 allFiles: true，没有默认广播到所有文件——因为该工具会在你可能正在编辑的文件中运行任意代码，包括被目标锁定的文件。传输层本就支持并发（sendCommand 一直接受目标文件键，每一跳都以请求 ID 为键）；只是工具层缺失。社区 PR #107，感谢 @Wolfr。另修复了一个 Desktop Bridge 中继 bug：自 resultAnalysis 和 fileContext 引入以来，该 bug 会静默地从每个 figma_execute 响应中丢弃这两个字段——导致工具描述要求调用者执行的 resultAnalysis.warning 检查变得不可能——现在由一个读取真实插件文件的测试加以守护。重新导入 manifest.json 以获取这两个字段；其余功能无需它也能工作，混合插件版本可干净降级。52 个测试套件 / 1443 个测试。

• v1.38.2 - 连接稳定性：孤儿回收器会终止健康的 MCP 服务器，这是所有 MCP 客户端反复出现 “服务器已断开” 错误的原因（在 Claude Code 和 Claude Desktop 中均已复现；与 Desktop Bridge 插件无关）。回收器在判定兄弟进程已死之前会探测其 /health，但它请求的是 127.0.0.1，而 WebSocket 服务器绑定的是 localhost——在双栈 macOS 上会解析为 IPv6 回环，而 IPv4 上什么都没有——因此探测对健康服务器报告 “没有任何响应”，所有基于该探测的 kill 安全门都沦为橡皮图章，包括那个为机器休眠后放过兄弟进程而编写的门。三个伴生缺陷：端口文件非原子写入（读取者在重写中途读到解析错误，两条清理路径都将其视为 “已损坏，删除它”，从而遗弃一个健康服务器）；一条孤儿路径在完全没有探测的情况下终止了无文件的端口持有者；以及一个心跳在其自身文件丢失后永久放弃。修复：探测 localhost、原子 temp+rename 写入、解析失败时绝不删除、两条路径都在孤儿终止前进行健康探测，以及由进程内端口所有权守护的自愈性重新通告。升级后请完全重启 MCP 客户端——旧版运行中的构建仍保留损坏的探测，仍会终止健康的兄弟进程。仅服务端，无需重新导入插件。1422 个测试（7 个新回归测试，每个都验证在修复前会失败）。

• v1.38.1 - 修复共享库变量工具。自 v1.29.0 发布以来，figma_get_library_variables 在所有方案、所有文件上都返回 totalCollections: 0；而 figma_import_library_variable 将失败的导入报告为成功，且 id: undefined。两者都将 Desktop Bridge 的 { success, result } 信封当作注入脚本的裸返回值来读取，因此 Array.isArray() 始终为 false，__error 守护是死代码，且 .id 始终为 undefined。失败以 成功 的形式呈现，并附带一条看似合理的提示（“通过 Assets 面板订阅库”），这正是它两个月未被报告的原因。两个工具现在都通过一个共享辅助函数解包，该函数还会将桥接层级的 success: false 映射到错误路径，因此插件超时会作为真实错误浮现，而不是被吞掉为 “0 个集合”；导入未产生 id 现在会显式报错。审计了全部 26 处 executeCodeViaUI 调用点——只有这两处受影响。测试 mock 曾编码了一种并不存在的线上契约，这就是 CI 一直保持绿色的原因；现在它们复现了真实的信封，另有六个回归测试经验证在修复前的源码上会失败。由 Isabella Minzly 报告。仅服务端——无需重新导入插件。

• v1.38.0 - 生成文档中的持续组件变更日志。figma_generate_component_doc 新增了一个可选 history 参数，用于生成真正的变更日志，而不仅仅是回显手写的 codeInfo.changelog 行：history.figma 遍历 Figma 版本历史，并对限定到该组件的每一对连续版本做差异比较（复用与 figma_diff_versions 相同的引擎，因此重命名、新增组件属性或令牌绑定都会各成一行），而 history.git 会在根据 codeInfo.filePath / sourceFiles[] 自动推导出的组件源文件上运行 git log。优先使用带标签的版本，但当文件没有标签版本时会自动使用自动保存——已在一个拥有 72 个自动保存、0 个带标签版本的成熟系统上验证，仅遍历带标签版本会一无所获。详细模式下的绑定按属性分组（否则将一个令牌绑定到一组 24 个变体，会在单个表格单元格中产生 44 条几乎相同的列表项）。两个来源默认关闭，因此现有调用方获得字节完全相同的输出。无新工具；仅服务端，无需重新导入插件。

• v1.37.0 - 面向每个 MCP 客户端的设计系统健康审计。新的 figma_audit_design_system_report 运行 Design System Dashboard 的确定性评分引擎（命名、令牌架构、组件元数据、可访问性、一致性、覆盖率），并将评分报告作为数据返回——无需 MCP Apps 支持或 ENABLE_MCP_APPS（之前的注册机制把一切都挡在门外，使得审计在 Claude Desktop 之外无法触达）。组件数据现在以实时为先：经过 fileKey 验证的逐页桥接爬取（每页 30 秒，按页隔离失败），并以 REST 已发布库作为回退；所选来源会在报告中披露（bridge-live / rest-published / none），因此过时发布评分无法冒充实时评分。输出在设计上就是令牌安全的：有界摘要、按类别分块的钻取、有上限的完整 JSON、5 分钟原始数据缓存。每条发现都带有修复判定——可由本 MCP 的写入工具自动修复、需在设计决策后修复、或手动修复——并指明具体工具。评分准确性通过：变体组件不再污染 PascalCase/大小写检查，接受 Title Case，组件集名称计入核心组件覆盖率，对比配对中识别 color/content/*，状态同义词（active≈pressed 等），并排除以 ./_ 开头的内部项。仅服务端——无需重新导入插件。

• v1.36.0 - 面向多文件并行工作的目标锁。figma_navigate 新增 lock: true 标志，用于固定活动文件——新的连接、重连以及用户在其他文件中的选择/页面更改不再移动命令目标，因此代理可以在用户处理另一个文件时安全地写入一个文件。当被固定的文件断开连接或导航离开时自动释放；figma_list_open_files 报告 targetLocked 标志，供写入前守卫使用。仅服务端——无需重新导入插件。

• v1.35.0 - Figma Slots 写入支持，通过社区 PR #77（由 @simonesalvucci 贡献）关闭了 #29（这可能是追踪器中最受期待的功能），并更新到 GA API。五个新工具：figma_create_slot（插槽 + 自动关联的 SLOT 属性；支持组件集内的变体——beta 限制已在 GA 时解除）、figma_get_slots、figma_append_to_slot（在实例插槽中克隆或创建内容；将克隆吸附到插槽原点）、figma_reset_slot，以及 figma_add_slot_property（将现有框架改造为插槽）。通过实况验证加固：恢复了 VARIANT defaultValue 的透传（Figma 要求非空）、在追加处理器中修复了破坏性路径的重排（在 clearExisting 清空任何内容之前先验证内容）、修复了 slot 负载的中继白名单。需要重新导入插件（code.js + ui.html 已更改）。

• v1.34.0 - 双向令牌同步 v2 + DTCG 2025.10。figma_import_tokens 现在应用 完整 的差异计划：缺失的集合和变量会被创建（模式、推断/记录的类型以及按依赖顺序设置的值——别名在第二遍处理），令牌路径重命名通过往返变量 ID 路由到更新阶段（不再有会在 replace 下永久销毁原始项的 create+delete 对），引用值通过四层解析器写入真实的 { type: "VARIABLE_ALIAS", id } 负载，删除则严格受 strategy: "replace" 门控。figma_export_tokens 新增 dtcgDialect: "2025"（从全精度浮点数生成对象形式颜色、对象尺寸），而旧版默认保持字节完全一致；导入无条件接受两种方言，并进行与方言无关的差异归一化。变量 scopes + codeSyntax 通过 $extensions["figma-console-mcp"] 往返。figma_setup_design_tokens 接受 DTCG 花括号引用（"{color.blue.600}"），这些引用会解析为真实别名，包括前向引用。新工具 figma_create_component_set 根据轴矩阵构建变体集（或合并现有组件），采用 Prop=Value 命名、可选自动排列网格，并在响应中返回变体键——带有按数量缩放的超时和失败回滚。需要重新导入插件（code.js + ui.html 已更改——组件集处理器和中继）。令牌/写入工具套件中共 183 个测试。

• v1.33.2 - 版本握手误报修复。v1.33.0 的握手将插件报告的版本与服务端的 包 版本进行比较，因此仅服务端的发布（如 v1.33.1 的依赖清理）会把每个最新的插件标记为过期，并对未更改的文件推送重新导入横幅。服务器现在改为与自己随附的 figma-desktop-bridge/code.js 中嵌入的 PLUGIN_VERSION 比较——这正是重新导入会安装的版本——而 PLUGIN_VERSION 本身现在意为 “插件文件发生更改的最后一个发布”（发布工具只会在 figma-desktop-bridge/ 自上一个标签以来确实发生变化时提升它）。figma_get_status 新增 transport.websocket.bundledPluginVersion；figma_diagnose 现在会归因到正确的版本。无新工具，无需重新导入插件（一次性例外：如果你在 v1.33.1 时重新导入过，横幅会再出现一次——用最后一次重新导入清除它）。1245 个测试通过（9 个新增）。

• v1.33.1 - 安全依赖清理。所有运行时和严重级别的 npm audit 告警均已通过范围内的版本提升解决（ws 8.21.0、hono 4.12.27、undici 7.28.0、handlebars 4.7.9——唯一一个严重级，且仅限开发——外加 lodash、path-to-regexp、basic-ftp、fast-uri、vite）。wrangler 有意保持在 4.72.0，因为更新版本要求 Node ≥22；剩余的唯一 audit 发现位于 wrangler/miniflare 的开发时工具链中，永远不会随 npm 包或 Worker 包发布。取代 dependabot PR #81/#82/#84。无代码更改、无 API 更改、无需重新导入插件。1236 个测试不变通过。

• v1.33.0 - 连接 UX 全面改造 + 全代码库审计。插件的状态胶囊现在基于实时连接状态，而非 Figma 的变量加载状态（以前在零个 MCP 服务器连接时也会亮绿）；HTTP /health 自动发现会自动重连已重启的服务器（包括“一死多活”的情况，以前是永久死胡同）；版本握手在需要重新导入时在插件 UI 上显示横幅，并在 figma_get_status/figma_diagnose 中呈现不匹配信息；云配对配置在插件重新打开后仍然保留，其状态行是派生且带标签的（不再有绿色胶囊下孤零零的 “已断开”）；所有插件文案均采用设计师语言。审计修复了 33 个已确认的问题：无损 DTCG 多模式往返、集合限定的跨集合别名、TIMING/EASING 映射到 DTCG duration/cubicBezier、两个缓存污染 bug（“搜索返回 0 个组件”的报告）、一个 CSWSH 源绕过（startsWith → 精确匹配）、睡眠后回收器的 kill 安全性（外加一个不使用 shell 的 /health 探测，用 os.devNull 避免 Windows curl 把健康的兄弟进程误判为无响应）、跨 REST 工具的分支 URL 正确性，以及桥接优先的 figma_take_screenshot。figma_arrange_component_set 现在会原地重新排列变体，使已放置的实例得以保留。无新工具；需要重新导入插件（code.js + ui.html 已更改——而且新的握手使得这次成为最后一次需要你自己发现的重新导入）。1236 个测试通过（33 个新增）。

• v1.32.1 - 文档生成器修复，由 Robin Di Capua 报告：figma_generate_component_doc 在填充/描边已绑定到变量时，仍将 颜色 记录为原始十六进制（Figma Variable 列显示 —），而间距令牌记录正确。两个根本原因——一个 id→name 查找读取了错误的键（读的是 .id/.name，而不是 variableId/variableName），以及变量名只会从仅限 Enterprise 的 REST /variables/local 端点获取（其他环境返回 403）。生成器现在通过 Desktop Bridge Plugin API 解析名称（所有方案均可用），并将其贯穿 States、Color Tokens 和 Spacing 表格，因此会显示 color/content/default、spacing/1 这样的真实令牌名。无新工具、无参数形态更改、无需重新导入插件。1203 个测试通过。

• v1.32.0 - 可访问性审计正确性修复，由 Isabella（无障碍协作伙伴）报告：figma_lint_design 会将低于 1.5 倍的行高标记为可访问性失败，影响了数百个组件。这是对 WCAG 1.4.12 文本间距 的误读：该标准要求内容能够 支持 用户间距覆盖而不丢失信息——而不是要求设计 以 1.5 倍 交付——因此低于 1.5 的行高并不构成一致性失败。行/段落间距检查现在限定于多行文本（单行标签和按钮豁免）；可读性提示（text-size、line-height、letter-spacing、paragraph-spacing）从 wcag 组中解耦出来，归入可选的 best-practice 组，因此默认审计（['wcag','design-system','layout']）和 rules: ['wcag'] 只返回真正的一致性结果；此外，figma_scan_code_accessibility 中新增的 text-spacing-support 代码侧建议会标记固定 px 的排版——这类排版实际上可以验证 1.4.12/1.4.4。无新工具、无参数形态更改；需要重新导入插件 以启用新的审计行为（桥接协议未变，因此未更新的插件仍然兼容）。1196 个测试通过。

• v1.31.0 - 修复了被报告最多的可靠性 bug：Desktop Bridge 连接断开后一直保持断开，直到你关闭插件、重启 MCP 客户端或手动杀掉端口。根本原因是 僵尸 MCP 服务器进程 在异常关闭后占用 WebSocket 端口范围（9223–9232）。回收器现在会从 SIGTERM 升级到 SIGKILL（忽略优雅关闭的挂起服务器不再能存活），通过一个 unref 的周期回收器每 5 分钟清扫一次端口范围，并且关停兜底机制会从一开始就防止服务器变成僵尸。重新设计的 Desktop Bridge 插件新增了一个自动重连看门狗（断开期间约每 12 秒重新探测一次）、一个上下文感知的 暂停 / 恢复 / 重新连接 按钮，以及一个实时服务器计数徽章。无新工具；需要重新导入插件（桥接 ui.html + code.js 已更改）。1190 个测试通过，包括一个集成测试，它启动一个真正忽略 SIGTERM 的进程，并断言回收器能将其杀死。

• v1.30.0 - 结构化写入工具中的原生变量绑定 + 字体排印，填补了过去不得不使用原始 figma_execute 的 Plugin API 空白。figma_set_fills / figma_set_strokes 接受 variableId，通过 setBoundVariableForPaint 将填充/描边绑定到颜色变量（任何方案，经由桥接）。figma_set_text 新增 fontFamily / fontStyle，具备对空格不敏感的归一化（SemiBold → Semi Bold）和优雅的 Regular 回退。figma_instantiate_component 在应用覆盖之前预先加载实例文本字体（修复了非 Regular 字重上文本覆盖被静默跳过的问题），并为失败的覆盖返回 warnings 数组。另修复了 figma_set_text 中的混合字体崩溃，以及一个会丢弃新消息字段的 ui.html 中继。无新工具；需要重新导入插件（桥接 ui.html + code.js 已更改）。已实况验证；1185 个测试通过。

• v1.29.2 - Bug 修复：figma_generate_component_doc 现在能忠实地渲染 Figma 组件描述，并可靠地标记原子设计层级。描述中的单个 # 标题现在渲染为真正的章节（使用指南、实现注意事项、可访问性要求、内容配置），而不是泄漏为 - # Heading 列表项；frontmatter description 取第一句，而不是在 “Accessibility” 一词处截断；生成的 Figma URL 不再重复 ?node-id=；组件的原子层级（atom/molecule/organism/template）通过单次 ids=<node> 文件请求 + 分隔线回溯自动检测，不依赖库发布。无新工具；无需重新导入插件。

• v1.29.1 - Bug 修复：figma_get_design_system_kit 现在以桥接优先的方式解析变量（Desktop Bridge / 云中继 → REST 回退），而不是直接调用仅限 Enterprise 的 Variables REST API。连接桥接时，非 Enterprise 用户不再在工具包的令牌部分遇到 403；REST 403 现在会将调用者引导回桥接，而不是走进死胡同。7 个新测试，总计 1185 个通过。无新工具；无需重新导入插件。

• v1.29.0 - 共享库检视：三个新工具弥合了 “我有一个组件键” 和 “我真的能使用它” 之间的鸿沟。figma_get_library_component_by_key 可将任意 40 字符的组件键解析为完整的 componentPropertyDefinitions + 变体（含已发布键）+ 每个变体的视觉规格——无需源库文件的 URL。figma_get_library_variables 通过 Plugin API 列出库令牌（适用于所有 Figma 方案；对应的 REST 仅限 Enterprise）。figma_import_library_variable 将库令牌导入当前文件，以便绑定到节点。27 个新测试，总计 1178 个通过。插件重新导入可选。

• v1.28.1 - Bug 修复补丁，源自对 v1.28.0 格式化器针对多层语义令牌设计系统的实战测试。修复：Tailwind v3 对纯别名集合生成空的 module.exports（现在将别名链解析为字面量值）；TypeScript module + JSON flat + JSON nested 格式化器将 "{alias.path}" 字符串作为字面量值输出（现已解析）；Tailwind v4 命名空间前缀重复（--color-theme-color-X 现在为 --color-theme-X）。新增公开辅助函数 resolveAliasChain。1151 个测试仍然通过。

• v1.28.0 - figma_export_tokens 的完整格式化器覆盖。七种新的输出格式：Tailwind v4 @theme inline、Tailwind v3 config、SCSS variables、TypeScript module、JSON

即将推出：

• 令牌同步 — 非 DTCG 输入解析器 - 用于非 DTCG 输入（Tokens Studio、CSS vars、Tailwind v4、Tailwind v3 config、SCSS、Style Dictionary v3、JSON flat/nested）的解析器，使 figma_import_tokens 能够导入与其导出相同的格式。（导入侧的应用扩展 — 创建、替换门控删除、别名目标更新 — 已在 v1.34.0 中发布。）

• 跨库变量解析 - 通过 getVariableByIdAsync 解析跨库别名，使其在导出中渲染为真正的 var(--target) 引用，而不是注释。

• 组件模板库 - 常见 UI 模式生成

• 视觉回归测试 - 截图差异比较能力

📖 完整路线图

💻 开发

git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install

# Local mode development
npm run dev:local

# Cloud mode development
npm run dev

# Build
npm run build

📖 开发指南

📄 许可证

MIT - 详见 LICENSE 文件。

🔗 链接

• 📚 文档站点 — 完整的指南、教程和 API 参考

• 📖 本地文档 — 文档源文件

• 🐛 报告问题

• 💬 讨论

• 🌐 Model Context Protocol

• 🎨 Figma API