figma-ui-mcp

figma-ui-mcp

Claude Code 到 Figma · Antigravity 到 Figma · Cursor 到 Figma · 任意 MCP IDE 到 Figma

_{✅ 已测试：Claude Code、Antigravity  |  🔧 兼容：Cursor、VS Code、Windsurf、Zed（任意 MCP stdio 客户端）}

双向 Figma MCP 桥接工具——让 AI 助手（Claude Code、Cursor、Windsurf、Antigravity、VS Code Copilot，或任意兼容 MCP 的 IDE）直接在 Figma 画布上绘制 UI，并将现有设计读取为结构化数据、屏幕截图或可直接用于代码的令牌。无需 Figma API 密钥——完全通过 localhost 运行。

需要 Figma Desktop——插件通过 localhost HTTP 轮询与 MCP 服务通信。Figma 网页应用不允许访问 localhost 网络，因此必须使用 Figma Desktop。

Claude ──figma_write──▶ MCP Server ──HTTP (localhost:38451)──▶ Figma Plugin ──▶ Figma Document
Claude ◀─figma_read──── MCP Server ◀──HTTP (localhost:38451)── Figma Plugin ◀── Figma Document

localhost 桥接的工作原理

MCP 服务会启动一个绑定到 localhost:38451 的小型 HTTP 服务。Figma 插件（在 Figma Desktop 内运行）使用长轮询——服务会将请求保持最多 8s，直到有任务到达；新操作进入队列时会立即刷新（近实时延迟 <100ms）。所有流量都留在你的计算机上——不会发送到任何外部服务。

**多实例支持（v2.3.0+）：**多个 Figma 文件/标签页可以同时连接。每个插件实例都会发送一个 sessionId，桥接工具会将操作路由到正确的会话。在 figma_write/figma_read 中使用可选的 sessionId 参数即可指定目标文件。

功能

v2.5 新特性

完整版本历史：参见 CHANGELOG.md。

快速入门

步骤 1 — 将 MCP 服务添加到你的 AI 客户端

选择你的平台：

# Project scope (default)
claude mcp add figma-ui-mcp -- npx figma-ui-mcp

# Global scope (all projects)
claude mcp add --scope user figma-ui-mcp -- npx figma-ui-mcp

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "figma": {
        "command": "npx",
        "args": ["-y", "figma-ui-mcp"]
      }
    }
  }
}

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-ui-mcp"]
    }
  }
}

git clone https://github.com/TranHoaiHung/figma-ui-mcp
cd figma-ui-mcp
npm install
# Then point your MCP client to: node /path/to/figma-ui-mcp/server/index.js

⚠️ 重要：添加 MCP 服务后，必须重启 IDE / AI 客户端（退出并重新打开）。 MCP 服务仅在启动时加载——仅保存配置文件是不够的。此要求适用于 Claude Code、Cursor、VS Code、Windsurf 和 Antigravity。

步骤 2 — 安装 Figma 插件

⬇ 下载 plugin.zip — 无需克隆 Git 仓库

1. 下载并将 plugin.zip 解压到你电脑上的任意位置
2. 打开 Figma Desktop（必需——Web 应用无法访问 localhost）
3. 前往 Plugins → Development → Import plugin from manifest...
4. 从解压后的文件夹中选择 manifest.json
5. 运行 Plugins → Development → Figma UI MCP Bridge

连接 MCP 服务后，插件界面会显示一个绿色圆点。

更新到较新版本

# Step 1 — get the new version + plugin path
npx figma-ui-mcp@latest --version
# figma-ui-mcp v2.5.12  —  plugin: /.../.npm/_npx/.../figma-ui-mcp/plugin

# Step 2 — restart Claude / your IDE so the MCP server reloads

# Step 3 — re-link the Figma plugin (manual, one-time per update)
#   Figma Desktop → Plugins → Development → Manage plugins in development
#   Remove old "Figma UI MCP Bridge" → "+" → Import plugin from manifest...
#   Select manifest.json from the plugin path printed in Step 1

# Step 4 — verify
#   Ask your AI: "figma_status"
#   pluginVersion in the response should match the npm version above

Figma 插件不会自动更新——每次插件变更后，都需要重新关联（步骤 3）。

步骤 3 — 将 AI 连接到 Figma

让你的 AI 助手连接：

"Connect to figma-ui-mcp"

AI 将调用 figma_status 并确认：

✅ Connected — File: "My Project", Page: "Page 1", Plugin v2.5.5

如果看到“Plugin not connected”，请确保 Figma 插件正在运行（步骤 2）。

步骤 4 — 使用提示词开始设计

连接后，只需用自然语言描述你的需求：

"Use figma-ui-mcp to draw a login screen for mobile"

AI 将自动：

1. 调用 figma_docs 加载 API 参考和设计规则
2. 调用 figma_read get_page_nodes 了解当前画布
3. 调用 figma_write 在 Figma 画布上创建设计
4. 调用 figma_read screenshot 验证结果

提示词示例

提升效果的小技巧

• 明确风格："dark theme"、"glassmorphism"、"minimal white" 能为 AI 指明清晰的方向
• 提及平台："mobile"（390×844）、"tablet"（768×1024）、"desktop"（1440×900）
• 迭代优化：第一次绘制完成后，说 "fix the spacing" 或 "make the buttons bigger"——AI 会读取并修改现有节点
• 使用选择：在 Figma 中选择一个画框，然后询问 "improve this design"——AI 会先读取你的选择
• 多屏流程："Now draw the signup screen next to the login screen"——AI 会将画框并排放置

工作流摘要

You: "Connect to figma-ui-mcp"
AI:  ✅ Connected to Figma

You: "Draw a mobile onboarding screen with 3 steps"
AI:  [calls figma_docs → figma_write → figma_read screenshot]
AI:  ✅ Done — here's what I created: [inline screenshot]

You: "The title text is not centered"
AI:  [calls figma_read get_selection → figma_write modify → screenshot]
AI:  ✅ Fixed — text is now centered

You: "Now draw the next onboarding screen beside it"
AI:  [reads page_nodes to find position → draws at x+440]
AI:  ✅ Done — 2 screens side by side

figma_status     — check connection (always call first)
figma_docs       — load API reference (call before drawing)
figma_write      — draw / modify UI on canvas
figma_read       — extract design data, screenshots, SVG

使用示例

绘制一个屏幕

向 Claude 提问："Draw a dark dashboard with a sidebar, header, and 4 KPI cards"

Claude 会调用 figma_write，并使用类似这样的代码：

await figma.createPage({ name: "Dashboard" });
await figma.setPage({ name: "Dashboard" });

const root = await figma.create({
  type: "FRAME", name: "Dashboard",
  x: 0, y: 0, width: 1440, height: 900,
  fill: "#0f172a",
});

const sidebar = await figma.create({
  type: "FRAME", name: "Sidebar",
  parentId: root.id,
  x: 0, y: 0, width: 240, height: 900,
  fill: "#1e293b", stroke: "#334155", strokeWeight: 1,
});

await figma.create({
  type: "TEXT", name: "App Name",
  parentId: sidebar.id,
  x: 20, y: 24, content: "My App",
  fontSize: 16, fontWeight: "SemiBold", fill: "#f8fafc",
});
// ... continue

读取设计

向 Claude 提问："Read my selected frame and convert it to Tailwind CSS"

Claude 会使用 operation: "get_selection" 调用 figma_read，接收完整的节点树， 然后生成相应的代码。

截取画框

figma_read  →  operation: "screenshot"  →  nodeId: "123:456"

返回一个 base64 PNG，Claude 可以对其进行分析和描述。

架构

figma-ui-mcp/
├── server/
│   ├── index.js            MCP server (stdio transport)
│   ├── bridge-server.js    HTTP bridge on localhost:38451 (long-poll, multi-session)
│   ├── code-executor.js    VM sandbox — safe JS execution + 7-lib icon fetcher
│   ├── tool-definitions.js MCP tool schemas (figma_status / _write / _read / _docs)
│   └── api-docs.js         API reference text (served to AI via figma_docs)
├── src/plugin/             Plugin source (concat-built into plugin/code.js)
│   ├── utils.js, svg-path-helpers.js, paint-and-effects.js, read-helpers.js
│   ├── handlers-write.js, handlers-read.js, handlers-read-detail.js,
│   │   handlers-library.js, handlers-tokens.js, handlers-write-ops.js
│   └── main.js
└── plugin/
    ├── manifest.json       Figma plugin manifest
    ├── code.js             Plugin main (auto-generated — 3600+ LOC)
    └── ui.html             Plugin UI — long-poll client + status dot

安全性

可用的写入操作（figma_write）

核心 CRUD

create / modify — 任何节点都可使用的高级属性：

页面管理

节点操作

组件

设计令牌与样式

applyVariable 支持的字段——将 FLOAT/COLOR/STRING/BOOLEAN 变量绑定到：

• 颜色：fill、stroke
• 几何属性：opacity、width、height、strokeWeight
• 圆角半径：cornerRadius 和单独的 topLeftRadius／topRightRadius／bottomLeftRadius／bottomRightRadius
• 间距（自动布局）：paddingTop、paddingBottom、paddingLeft、paddingRight、itemSpacing、counterAxisSpacing
• 排版（TEXT 节点）：fontSize、letterSpacing、lineHeight、paragraphSpacing、paragraphIndent
• 字体替换（STRING）：fontFamily、fontStyle、characters——通过一个变量即可将 Inter 替换为 SF Pro
• 可见性（BOOLEAN）：visible

图像与图标辅助工具（服务端）

loadIcon 回退优先级（优先填充样式，首选 iOS 风格）： Ionicons（iOS 填充） → Fluent UI（Win11 填充） → Bootstrap（填充） → Phosphor（填充） → Tabler Filled（4,500+） → Tabler Outline → Lucide（轮廓样式回退）

可免费替代付费的 Icons8 ios-filled。Ionicons 命名注意事项：Bell→notifications、Back→chevron-back、Clock→time、Fire→flame、Lightning→flash、Lock→lock-closed。

原型与交互

支持的过渡效果：SMART_ANIMATE、DISSOLVE、MOVE_IN、MOVE_OUT、PUSH、SLIDE_IN、SLIDE_OUT、INSTANT 支持的缓动效果：LINEAR、EASE_IN、EASE_OUT、EASE_IN_AND_OUT、CUSTOM_BEZIER

滚动行为

变体与组件替换

可用的读取操作（figma_read）

includeHidden 参数（布尔值，默认值为 false）— 适用于 get_selection、get_design、search_nodes、scan_design。当值为 false（默认值）时，会跳过 visible: false 的节点。传入 true 可包含隐藏图层。

使用现有项目

打开已有设计系统的 Figma 文件时，始终先读取，再绘制。

步骤 1 — 读取现有内容

figma_read get_variables      → load variable IDs (Design Tokens)
figma_read get_styles         → load paint/text style IDs and hex values
figma_read get_local_components → load component IDs
figma_read get_page_nodes     → load top-level frame IDs

步骤 2 — 在 figma_write 中构建查找映射

// Load variables → build varMap: name → id
var vars = await figma.get_variables();
var varMap = {};
for (var ci = 0; ci < vars.collections.length; ci++) {
  var col = vars.collections[ci];
  for (var vi = 0; vi < col.variables.length; vi++) {
    var v = col.variables[vi];
    varMap[v.name] = v.id;
  }
}

// Load styles → build colorMap: name → hex, textMap: name → {fontSize, fontWeight}
var styles = await figma.get_styles();
var colorMap = {}, textMap = {};
styles.paintStyles.forEach(function(s) { colorMap[s.name] = s.hex; });
styles.textStyles.forEach(function(s)  { textMap[s.name]  = s; });

// Load components → build compMap: name → id
var comps = await figma.get_local_components();
var compMap = {};
comps.components.forEach(function(c) { compMap[c.name] = c.id; });

步骤 3 — 使用发现的值创建节点

// Use colorMap for fill (hex from existing styles)
var card = await figma.create({
  type: "FRAME", name: "Card",
  fill: colorMap["color/bg-surface"] || "#FFFFFF",
  width: 360, height: 200,
  layoutMode: "VERTICAL", paddingTop: 16, paddingLeft: 16,
  paddingBottom: 16, paddingRight: 16, itemSpacing: 12,
});

// Then bind variables so light/dark mode switches propagate
if (varMap["bg-surface"])
  await figma.applyVariable({ nodeId: card.id, field: "fill",        variableId: varMap["bg-surface"] });
if (varMap["radius-md"])
  await figma.applyVariable({ nodeId: card.id, field: "cornerRadius",variableId: varMap["radius-md"] });
if (varMap["spacing-md"])
  await figma.applyVariable({ nodeId: card.id, field: "paddingTop",  variableId: varMap["spacing-md"] });

步骤 4 — 使用覆盖属性实例化组件

// Prefer existing components over drawing from scratch
if (compMap["btn/primary"]) {
  await figma.instantiate({
    componentId: compMap["btn/primary"],
    parentId: card.id,
    overrides: { "Label": { text: "Confirm", fill: "#FFFFFF" } }
  });
}

步骤 5 — 将帧固定为 Light / Dark 模式

var collection = vars.collections.find(function(c) { return c.name === "Design Tokens"; });

// Duplicate frame and preview both modes side by side
var frames = await figma.get_page_nodes();
var homeId  = frames.find(function(f) { return f.name === "Home"; }).id;
var light   = await figma.clone({ id: homeId, x: 0,    name: "Preview/Light" });
var dark    = await figma.clone({ id: homeId, x: 1540, name: "Preview/Dark"  });
await figma.setFrameVariableMode({ nodeId: light.id, collectionId: collection.id, modeName: "light" });
await figma.setFrameVariableMode({ nodeId: dark.id,  collectionId: collection.id, modeName: "dark"  });

完整 API 参考和所有设计规则：在 AI 客户端中运行 figma_docs。

Star History

如果 figma-ui-mcp 对你有帮助，请给它点个星 — 这有助于其他人发现这个项目！

许可证

MIT © TranHoaiHung — 可免费使用、修改和分发。详情请参阅 LICENSE。

关键词

Figma MCP、Claude Code 转 Figma、Cursor 转 Figma、AI 转 Figma、Figma AI 插件、Figma MCP 桥接器、Figma MCP 服务、Figma 设计转代码、代码转 Figma 设计、AI UI 设计、Figma 自动化、Figma AI 插件、Model Context Protocol Figma、Claude Figma、Windsurf Figma、VS Code Figma、Antigravity Figma、AI 设计工具、Figma API 替代方案、Figma 本地主机插件、用 AI 绘制 UI、AI 生成 Figma 设计、Figma AI 设计系统、Figma MCP 服务、读取 Figma 设计、写入 Figma 设计、双向 Figma、Figma 桌面插件、npx figma-ui-mcp