figma-bridge-mcp

让 AI 在你的 Figma 画布上绘图，并将设计读回为代码。

面向 Figma Desktop 的双向 Model Context Protocol 桥接工具。
无需 Figma API 密钥。无需云服务。所有操作均在 localhost 上运行。

快速开始 · 工作原理 · 工具 · 安全模型 · 故障排除 · 更新日志

与 Figma, Inc. 无关联，未经其认可或赞助。“Figma”是 Figma, Inc. 的商标，在此仅用于描述兼容性。

概述

figma-bridge-mcp 将 AI 助手连接到你在 Figma Desktop 中打开的文档。

需要 Figma Desktop。 插件通过 localhost 与服务通信，而 Figma 网页应用不允许这样做。

工作原理

三个部分协同工作：你的 AI 客户端、MCP 服务（Node）和 Figma 插件（运行在 Figma Desktop 内）。插件会轮询服务，因此无需向 Figma 发起任何入站连接。

flowchart LR
  subgraph Client["AI client"]
    A["Claude Code · Cursor · Windsurf<br/>VS Code · Antigravity · any MCP client"]
  end
  subgraph Server["figma-bridge-mcp  (Node)"]
    B["MCP server<br/>5 tools · stdio"]
    C["Code sandbox<br/>runs figma_write code"]
    D["HTTP bridge<br/>127.0.0.1:47451"]
  end
  subgraph Figma["Figma Desktop"]
    E["Plugin UI<br/>long-poll client"]
    F["Plugin main thread<br/>66 operations"]
    G[("Figma document")]
  end
  A <-->|"MCP / stdio"| B
  B --> C
  C --> D
  B --> D
  D <-->|"HTTP long-poll"| E
  E <-->|postMessage| F
  F <--> G

一次往返

服务会让每次轮询保持打开状态，最长 8 s；一旦有工作排队，就立即响应，因此延迟通常低于 100 ms。

sequenceDiagram
  autonumber
  participant AI as AI client
  participant S as MCP server
  participant B as Bridge :47451
  participant P as Figma plugin
  AI->>S: figma_write { code }
  S->>S: run code in sandbox
  S->>B: queue operation (create, modify, …)
  P->>B: GET /poll  (held up to 8 s)
  B-->>P: operations
  P->>P: apply to the Figma document
  P->>B: POST /response { id, data }
  B-->>S: resolve operation
  S-->>AI: result + logs

同时打开多个 Figma 文件

每个打开的插件实例都会注册自己的 会话。传入可选的 sessionId 至 figma_write / figma_read，即可指定目标文件；如果该会话未连接，调用会失败，而不会写入其他文件。

快速开始

1 · 将 MCP 服务添加到你的客户端

claude mcp add figma-bridge-mcp -- npx @hanoilab/figma-bridge-mcp          # this project
claude mcp add --scope user figma-bridge-mcp -- npx @hanoilab/figma-bridge-mcp   # all projects

{
  "mcpServers": {
    "figma": { "command": "npx", "args": ["-y", "@hanoilab/figma-bridge-mcp"] }
  }
}

{
  "mcp": {
    "servers": {
      "figma": { "command": "npx", "args": ["-y", "@hanoilab/figma-bridge-mcp"] }
    }
  }
}

git clone https://github.com/nguyendinhphongdx/figma-bridge-mcp
cd figma-bridge-mcp && npm install
# point your MCP client at: node /path/to/figma-bridge-mcp/server/index.js

编辑配置后，请重启客户端。 MCP 服务仅在启动时加载。

2 · 安装 Figma 插件

1. ⬇ 下载插件，并解压到任意位置。
2. 在 Figma Desktop 中：Plugins → Development → Import plugin from manifest…，然后选择 manifest.json。
3. 运行 Plugins → Development → Bridge MCP for Figma。

插件连接到服务后，窗口会显示一个绿色圆点。

3 · 连接并设计

告诉你的助手：

“连接到 figma-bridge-mcp”

它会调用 figma_status，并确认文件、页面和插件版本。然后只需描述你的需求：

“绘制一个带有 Apple 和 Google 登录按钮的移动端登录界面。”

flowchart LR
  P["Your prompt"] --> D["figma_docs<br/>load API + design rules"]
  D --> R["figma_read<br/>inspect the canvas"]
  R --> W["figma_write<br/>draw / modify"]
  W --> S["figma_read screenshot<br/>verify"]
  S -->|"needs fixes"| W
  S -->|"looks right"| Done(["Done"])

更新

npx @hanoilab/figma-bridge-mcp@latest --version   # prints the new version and the plugin path

重启客户端，然后从输出的路径重新导入 manifest.json（Plugins → Development → Manage plugins in development）。Figma 插件不会自动更新。运行 figma_status 并检查 pluginVersion 是否匹配。

工具

该服务提供五个 MCP 工具。

设计转代码

flowchart LR
  F["Select a frame<br/>in Figma"] --> A["get_design_context<br/>layout · tokens · typography"]
  F --> B["get_css<br/>ready-to-paste CSS"]
  F --> C["get_component_map<br/>instances + import paths"]
  A --> AI(["AI generates<br/>React · Vue · Swift · Tailwind"])
  B --> AI
  C --> AI

figma_write — 47 项操作

代码在包含 figma 对象的沙盒中运行；每次调用相互独立，因此请在每次调用开始时重新查询节点 ID。

const root = await figma.create({
  type: "FRAME", name: "Dashboard", width: 1440, height: 900, fill: "#0f172a",
});
const sidebar = await figma.create({
  type: "FRAME", name: "Sidebar", parentId: root.id,
  width: 240, height: 900, fill: "#1e293b", stroke: "#334155", strokeWeight: 1,
});
await figma.create({
  type: "TEXT", parentId: sidebar.id, x: 20, y: 24,
  content: "My App", fontSize: 16, fontWeight: "SemiBold", fill: "#f8fafc",
});

默认跳过隐藏图层；在 get_selection、get_design、search_nodes 或 scan_design 中传入 includeHidden: true 即可包含隐藏图层。

const vars = await figma.get_variables();
const varMap = {};
vars.collections.forEach(c => c.variables.forEach(v => { varMap[v.name] = v.id; }));

const card = await figma.create({
  type: "FRAME", name: "Card", width: 360, height: 200,
  layoutMode: "VERTICAL", paddingTop: 16, paddingLeft: 16, paddingBottom: 16, paddingRight: 16, itemSpacing: 12,
});
await figma.applyVariable({ nodeId: card.id, field: "fill", variableId: varMap["bg-surface"] });
await figma.applyVariable({ nodeId: card.id, field: "cornerRadius", variableId: varMap["radius-md"] });

安全模型

此桥接没有登录机制，因此访问权限由网络边界控制；figma_write 代码按与用户相同的信任级别对待。

flowchart LR
  R["HTTP request"] --> O{"Origin missing<br/>or 'null'?"}
  O -->|no| X1["403 — web page"]
  O -->|yes| H{"Host is<br/>loopback?"}
  H -->|no| X2["403 — DNS rebinding"]
  H -->|yes| A{"Operation on<br/>the allowlist?"}
  A -->|no| X3["400"]
  A -->|yes| Q["Queued for the plugin"]

发现漏洞？请参阅 SECURITY.md。

配置

故障排查

项目结构

figma-bridge-mcp/
├── server/                 npm package: MCP server + bridge
│   ├── index.js            MCP entry (stdio) and tool handlers
│   ├── bridge-server.js    HTTP bridge: long-poll, sessions, origin gate
│   ├── code-executor.js    sandbox for figma_write
│   ├── figma-proxy.js      the figma.* API seen by user code
│   ├── http-fetch.js       guarded fetch for images and icons
│   ├── allowed-ops.js      operation allowlist
│   └── docs/               reference served by figma_docs
├── src/plugin/             plugin source (plain files, concatenated)
├── plugin/                 manifest.json, ui.html, code.js (generated)
└── scripts/                build, test runner, regression tests

开发

npm install
npm run build:plugin    # src/plugin/*.js  →  plugin/code.js  (generated — never edit by hand)
npm test                # every scripts/test-*.mjs; no live Figma needed

插件文件串联后共享同一作用域；文件顺序由 scripts/lib/plugin-files.mjs 决定。更改任何内容前，请参阅 CLAUDE.md，了解需要知晓的不变量。

**发布：**在 package.json 中提升 version，将 CHANGELOG.md 顶部标题重命名为 ## [x.y.z] — date，然后推送到 main。CI 会运行测试、发布到 npm、为提交打标签、创建附带插件 zip 的 GitHub Release，并更新 MCP Registry。

许可证

MIT © nguyendinhphongdx。本项目从 TranHoaiHung/figma-ui-mcp 分叉而来；原始版权声明保留在 LICENSE 中。