Figma MCP Bridge

🚀 Figma MCP Bridge

Figma MCP Bridge 是一款基於模型上下文協議（MCP）的服務器，它藉助 WebSocket 橋接至 Figma 插件，賦能 Claude 即時讀取和操作 Figma 文檔。

✨ 主要特性

• 62 種 Figma 操作：涵蓋創建圖形、修改樣式、管理組件、導出資源等功能。
• 即時雙向通信：操作更改可在 Figma 中即時呈現。
• 令牌優化查詢：通過高效的變量搜索和節點遍歷，提升與 AI 的交互效率。
• 全面訪問 Figma API：支持樣式、變量、自動佈局、布爾運算等功能。

🏗️ 架構

Claude Code ←──stdio──→ MCP Server ←──WebSocket──→ Figma Plugin ←──→ Figma API
                        (Node.js)    localhost:3055    (runs in Figma)

🚀 快速開始

🔍 前提條件

• Node.js 18 及以上版本
• Figma 桌面應用程序
• Claude Code CLI 或 Claude 桌面應用

📦 安裝

選項 A：從 npm 安裝（推薦）

針對 Claude Code CLI：

claude mcp add figma-mcp-bridge -- npx @magic-spells/figma-mcp-bridge

針對 Claude 桌面應用：

編輯配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

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

然後重啟 Claude 桌面應用。

安裝 Figma 插件：

• 從本倉庫下載 plugin 文件夾。
• 在 Figma 中，選擇 插件 → 開發 → 從清單導入插件。
• 選擇 plugin/manifest.json 文件。

連接：

• 打開一個 Figma 文件。
• 運行插件：插件 → 開發 → Claude Figma Bridge。
• 狀態應顯示為“已連接”。

選項 B：從源代碼安裝

1. 克隆倉庫

   git clone https://github.com/magic-spells/figma-mcp-bridge.git
   cd figma-mcp-bridge
   npm install
   

2. 添加到 Claude Code

   claude mcp add figma-mcp-bridge node /path/to/figma-mcp-bridge/src/index.js
   

3. 安裝 Figma 插件

   • 在 Figma 中，選擇 插件 → 開發 → 從清單導入插件。
   • 選擇克隆倉庫中的 plugin/manifest.json 文件。

4. 連接

• 打開一個 Figma 文件。
• 運行插件：插件 → 開發 → Claude Figma Bridge。
• 狀態應顯示為“已連接”。

⚙️ 配置

🌐 環境變量

✅ 自動批准 Figma 工具

在 .claude/settings.local.json 中添加以下內容：

{
  "permissions": {
    "allow": ["mcp__figma-mcp-bridge__*"]
  }
}

📄 命令參考

🔍 查詢命令

figma_get_context

獲取當前 Figma 文檔的上下文信息，包括文件信息、當前頁面和所選內容。

figma_list_pages

列出當前 Figma 文檔中的所有頁面。

figma_get_nodes

根據節點 ID 獲取特定節點的詳細信息。

figma_get_local_styles

列出文檔中定義的所有本地樣式。

figma_get_local_variables

獲取所有本地變量和變量集合。

注意：該命令可能返回超過 25000 個令牌。為提高效率，建議使用 figma_search_variables。

figma_get_children

獲取節點的直接子節點。適用於逐層瀏覽節點層次結構。

figma_search_nodes

在指定範圍內按名稱搜索節點。推薦用於查找特定的框架、部分或元素。

每個節點返回約 50 個令牌，而完整節點數據約為 500 個令牌。

figma_search_components

按名稱搜索本地組件。適用於查找特定的組件，如“Button”、“Header”等。

figma_search_styles

按名稱搜索本地樣式。在查找特定樣式時，比 figma_get_local_styles 更高效。

🆕 創建命令

figma_create_rectangle

創建一個新的矩形。

figma_create_ellipse

創建一個橢圓、圓形、弧形或環形。

figma_create_line

創建一條線。

figma_create_frame

創建一個框架容器（支持自動佈局）。

figma_create_text

創建一個文本節點。

figma_clone_nodes

克隆（複製）節點。

figma_create_component

創建一個可重複使用的組件。

figma_create_instance

創建一個組件的實例。

💅 樣式命令

figma_set_fills

設置節點的填充顏色。

顏色格式：

• 十六進制：{ color: "#FF0000" } 或 { color: "#FF0000AA" }（包含透明度）
• RGB：{ r: 1, g: 0, b: 0, a: 0.5 }
• 完整數組：[{ type: "SOLID", color: { r, g, b }, opacity: 1 }]

figma_set_strokes

設置節點的描邊顏色。

figma_set_text

設置文本節點的文本內容。

figma_set_opacity

設置節點的透明度。

figma_set_corner_radius

設置節點的圓角半徑。

figma_set_effects

設置節點的效果（陰影、模糊等）。

陰影效果：

{
  "type": "DROP_SHADOW",
  "color": { "color": "#000000" },
  "offset": { "x": 0, "y": 4 },
  "radius": 8,
  "spread": 0,
  "visible": true
}

模糊效果：

{
  "type": "LAYER_BLUR",
  "radius": 10,
  "visible": true
}

figma_apply_style

將本地樣式應用到節點。

figma_set_variable

設置變量值或將變量綁定到節點屬性。

📐 佈局命令

figma_set_auto_layout

配置框架的自動佈局。

figma_set_layout_align

設置子節點在自動佈局中的對齊方式。

🚚 轉換命令

figma_move_nodes

將節點移動到新的位置。

figma_resize_nodes

調整節點的大小。

figma_delete_nodes

刪除節點。

figma_group_nodes

將多個節點組合成一個組。

figma_ungroup_nodes

將組節點解組。

figma_rename_node

重命名節點。

figma_reorder_node

更改節點的 z 軸順序（圖層順序）。

figma_set_constraints

設置調整大小的約束條件（僅適用於非自動佈局的框架）。

🧭 導航命令

figma_set_selection

設置當前的選擇內容。

figma_set_current_page

切換到不同的頁面。

📤 導出命令

figma_export_node

將節點導出為圖像。

返回 base64 編碼的數據。

🧩 組件命令

figma_detach_instance

將實例從組件中分離（轉換為框架）。

🔍 令牌優化

變量查詢

建議使用 figma_search_variables 替代 figma_get_local_variables：

// 效率較低（約 25000 個以上令牌）
figma_get_local_variables({ type: 'ALL' })

// 效率較高（約 500 個令牌）
figma_search_variables({
  namePattern: 'tailwind/orange/*',
  type: 'COLOR',
  compact: true,
  limit: 50
})

figma_search_variables 參數：

節點遍歷

在 figma_get_nodes 中使用 depth 參數：

查找節點

使用搜索工具替代遍歷整個樹：

// 在頁面/框架內按名稱查找節點
figma_search_nodes({
  parentId: '1:2',           // 必需的搜索範圍
  nameContains: 'button',    // 不區分大小寫
  types: ['FRAME', 'COMPONENT'],
  compact: true
})

// 逐層瀏覽層次結構
figma_get_children({ parentId: '1:2' })

// 按名稱查找組件
figma_search_components({ nameContains: 'Header' })

// 按名稱查找樣式
figma_search_styles({ nameContains: 'primary', type: 'PAINT' })

❗ 已知限制

• 插件代碼中不支持 ES6 擴展運算符
• 布爾運算要求節點具有相同的父節點
• 約束不適用於自動佈局的子節點（請使用 layoutAlign）
• 線條的高度為 0，請使用 length 參數
• 向量僅支持 M、L、Q、C、Z 命令（不支持弧線）
• detachInstance() 也會分離祖先實例
• 所有命令的超時時間為 30 秒

🛠️ 故障排除

插件無法連接

1. 確保 MCP 服務器正在運行。
2. 檢查端口：默認端口為 3055，或設置 FIGMA_BRIDGE_PORT。
3. 在 Figma 中重啟插件。
4. 點擊插件 UI 中的“重新連接”按鈕。

端口已被使用

服務器會自動嘗試 3055 - 3070 之間的端口。若要使用特定端口，請執行以下命令：

FIGMA_BRIDGE_PORT=3057 node src/index.js

多個 Claude Code 實例

每個 Claude Code 實例可以通過使用不同的端口與不同的 Figma 文件配合使用：

1. 第一個實例：使用默認端口 3055。
2. 第二個實例：設置 FIGMA_BRIDGE_PORT=3056。
3. 在 Figma 插件中：在插件 UI 中更改端口號以匹配。

插件 UI 中有一個端口輸入字段，可通過更改該字段連接到不同的 MCP 服務器。

命令超時

• 命令的超時時間為 30 秒。
• 大型導出可能會超時，請嘗試較小的導出比例。
• 檢查插件是否仍處於連接狀態（綠色狀態）。

字體錯誤

文本操作需要加載字體。插件會自動處理此問題，但如果字體未安裝，操作將失敗。請使用系統中可用的字體。

📄 許可證

本項目採用 MIT 許可證。