Figma Forge

AI 驱动的 Figma 设计引擎 — 让 Claude Code 直接在 Figma 中创造设计稿。

<p align="center"> <code>Claude Code</code> → <code>MCP</code> → <code>Bridge Server</code> → <code>WebSocket</code> → <code>Figma Plugin</code> </p>

---

为什么需要 Figma Forge

痛点	现状	Figma Forge
官方 API 限流	120 req/min，复杂文件频繁 429	Plugin API，无调用限制
只能读不能写	REST API 单向	完整的创建 / 修改 / 删除
每次调用走网络	高延迟、易超时	WebSocket 本地通信，毫秒级响应
手动设计效率低	重复操作、无法批量	AI 一次指令，52 个语义工具自动编排

架构

flowchart TD
    A["Claude Code<br/>AI 理解意图, 调用语义工具"]
    B["Figma Forge Bridge<br/>MCP Server · Semantic Layer · REST API"]
    C["Figma Plugin<br/>在 Figma 沙箱中执行 Plugin API"]
    D["Figma Desktop<br/>设计稿实时渲染"]

    A -- "MCP (stdio)" --> B
    B -- "WebSocket (localhost:37849)" --> C
    C -- "Plugin API" --> D

核心设计：AI 只说"做什么"（create_button({ variant: "primary" })），Bridge 负责"怎么做"（自动编排 createNode → setLayout → createText）。一次 Tool Call 完成复杂设计操作。

---

特性一览

<details> <summary><b>🎨 设计创建</b> — 19 个语义工具</summary>

一次调用即可生成完整的 UI 组件，无需手动拼装底层 API。

类别	工具
基础	create_container · create_text
UI 组件	create_button · create_card · create_input · create_avatar · create_icon · create_image · create_divider · create_badge
布局	create_header · create_sidebar · create_grid · create_list · create_form · create_modal · create_toast · create_navigation · create_hero

</details>

<details> <summary><b>✏️ 设计修改</b> — 6 个语义工具</summary>

支持按 ID 精确操作，也支持按语义标签批量操作。

工具	说明
update_node / update_by_semantic	更新属性（单个 / 批量）
delete_node / delete_by_semantic	删除节点（单个 / 批量）
move_node / reorder_by_semantic	移动与重排

</details>

<details> <summary><b>🔍 设计读取</b> — 6 个语义工具</summary>

工具	说明
get_document_info	文档名称、页面列表
get_node_tree	递归获取节点层级
get_node_properties	获取节点属性
find_nodes	按名称 / 类型 / 语义搜索
get_styles	样式信息
get_semantic_map	语义注册表

</details>

<details> <summary><b>🏗️ 高级能力</b> — 设计 Token · 变体 · Diff · 模板</summary>

能力	工具	说明
Variables	create_variable_collection · create_variable · get_variables · update_variable · delete_variable	设计 Token CRUD，支持 light/dark 多模式
Variants	create_component_set · create_variant_instance · update_variant · get_component_sets	组件变体的创建与实例化
Diff Engine	diff_snapshot · diff_apply	增量更新，只发送变化的属性
Templates	create_from_template · list_templates · save_as_template	预定义模板 + 参数化生成
Batch	batch_execute	批量执行，失败自动回滚
Events	start_event_listener · stop_event_listener · get_pending_events	实时监听文档变化
Export	export_node · export_by_semantic	导出为 PNG / JPG / SVG / PDF

</details>

---

快速开始

前置条件

依赖	版本	说明
Figma Desktop	—	⚠️ Web 版不支持 Plugin API
Node.js	≥ 18	运行 Bridge Server
Claude Code	—	CLI 或 VS Code 插件均可

安装

方式一：从 npm（推荐）

npx @figma-forge/core setup

方式二：从源码

git clone <repo-url> && cd Figma-Forge
pnpm install && pnpm build

在 Figma 中导入 Plugin

1. 打开 Figma Desktop（不是 Web 版）
2. Plugins → Development → Import plugin from manifest...
3. 选择文件：
   • npm 安装 → ~/.figma-forge/plugin/manifest.json
   • 源码安装 → packages/plugin/manifest.json

开始使用

# 在项目目录启动 Claude Code（它会自动启动 Bridge Server）
cd <your-project>
claude

在 Figma 中右键 → Plugins → Figma Forge，看到 "Connected to Bridge" 后即可对话：

你: 帮我创建一个登录页面
Claude: (调用 create_form → create_button → create_input，Figma 中实时生成)

⚠️ 不要手动启动 Bridge Server。 Claude Code 通过 .mcp.json 自动管理其生命周期，手动启动会导致端口冲突。

---

工作区布局

使用时需要三个窗口同时工作：

flowchart LR
    subgraph T1["Terminal 1"]
        A["Claude Code<br/>输入设计需求<br/>AI 调用 Semantic Tools"]
    end
    subgraph APP["App Window"]
        B["Figma Desktop<br/>设计稿实时生成<br/>52 种组件可用"]
    end
    subgraph EMBED["Figma 内嵌"]
        C["Plugin Panel<br/>显示连接状态<br/>执行日志"]
    end

    A <--> B
    C -. "WebSocket" .-> B

Bridge Server 由 Claude Code 在后台自动启动，无需额外操作。

---

开发

pnpm build                  # 构建所有包
pnpm dev:bridge             # 单独调试 Bridge（⚠️ 不要和 Claude Code 同时使用）
node test-e2e.mjs           # 运行端到端测试

技术栈

层级	技术
Plugin	TypeScript · Figma Plugin API
Bridge	TypeScript · Node.js · @modelcontextprotocol/sdk · WebSocket (ws)
构建	esbuild + tsc · pnpm monorepo

REST API

Bridge Server 同时提供 HTTP 接口，可作为 MCP 的补充：

curl http://localhost:37850/health                                    # 健康检查
curl -X POST http://localhost:37850/tools/get_document_info           # 获取文档信息
curl -X POST http://localhost:37850/tools/create_container \
  -H "Content-Type: application/json" \
  -d '{"name": "my-frame", "direction": "VERTICAL", "padding": 16}'  # 创建容器

---

故障排查

问题	排查步骤
Plugin 显示 "Disconnected"	① 确认 Figma Desktop（非 Web） ② 确认 Claude Code 已启动 ③ 查看终端是否有 [Bridge] ✅ Plugin connected ④ 在 Plugin 面板等待自动重连
MCP server failed to start	① node --version ≥ 18 ② 在 .mcp.json 所在目录启动 Claude Code ③ 确认 pnpm build 已执行
端口冲突 EADDRINUSE	不要同时手动启动 Bridge 和 Claude Code。查找占用进程：lsof -i :37849（macOS/Linux）或 netstat -ano | findstr :37849（Windows）