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_BRIDGE_PORT	3055	WebSocket 服務器端口（若端口繁忙，將自動遞增）

✅ 自動批准 Figma 工具

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

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

📄 命令參考

🔍 查詢命令

figma_get_context

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

參數	類型	描述
(無)

figma_list_pages

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

參數	類型	描述
(無)

figma_get_nodes

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

參數	類型	是否必需	描述
nodeIds	string[]	是	節點 ID 數組（例如，["1:23", "4:56"]）
depth	string	否	詳細程度：minimal、compact 或 full（默認）

figma_get_local_styles

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

參數	類型	是否必需	描述
type	string	否	過濾器：PAINT、TEXT、EFFECT、GRID 或 ALL（默認）

figma_get_local_variables

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

參數	類型	是否必需	描述
type	string	否	過濾器：COLOR、FLOAT、STRING、BOOLEAN 或 ALL（默認）

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

figma_get_children

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

參數	類型	是否必需	默認值	描述
parentId	string	是		要獲取子節點的父節點 ID
compact	boolean	否	true	返回最少的數據

figma_search_nodes

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

參數	類型	是否必需	默認值	描述
parentId	string	是		搜索範圍（頁面/框架/部分 ID）
nameContains	string	否		不區分大小寫的子字符串匹配
namePattern	string	否		帶有通配符的全局模式（例如，*button*）
types	string[]	否		按節點類型過濾：FRAME、TEXT、SECTION、COMPONENT、INSTANCE、GROUP 等
maxDepth	number	否	-1	搜索深度（-1 表示無限制，1 表示直接子節點）
compact	boolean	否	true	返回最少的數據
limit	number	否	50	最大結果數

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

figma_search_components

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

參數	類型	是否必需	默認值	描述
nameContains	string	否		不區分大小寫的子字符串匹配
namePattern	string	否		帶有通配符的全局模式
includeVariants	boolean	否	false	是否包含組件集中的單個變體
compact	boolean	否	true	返回最少的數據
limit	number	否	50	最大結果數

figma_search_styles

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

參數	類型	是否必需	默認值	描述
nameContains	string	否		不區分大小寫的子字符串匹配
type	string	否	"ALL"	過濾器：PAINT、TEXT、EFFECT、GRID、ALL
compact	boolean	否	true	返回最少的數據
limit	number	否	50	最大結果數

🆕 創建命令

figma_create_rectangle

創建一個新的矩形。

參數	類型	是否必需	默認值	描述
x	number	否	0	X 座標位置
y	number	否	0	Y 座標位置
width	number	否	100	寬度（像素）
height	number	否	100	高度（像素）
name	string	否	"Rectangle"	節點名稱
fills	color	否		填充顏色
parentId	string	否		父節點 ID

figma_create_ellipse

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

參數	類型	是否必需	默認值	描述
x	number	否	0	X 座標位置
y	number	否	0	Y 座標位置
width	number	否	100	寬度（圓形的直徑）
height	number	否	100	高度
name	string	否	"Ellipse"	節點名稱
fills	color	否		填充顏色
parentId	string	否		父節點 ID
arcData.startingAngle	number	否		起始角度（弧度）
arcData.endingAngle	number	否		結束角度（弧度）
arcData.innerRadius	number	否		環形的內半徑比例（0 - 1）

figma_create_line

創建一條線。

參數	類型	是否必需	默認值	描述
x	number	否	0	X 座標位置
y	number	否	0	Y 座標位置
length	number	否	100	線的長度
rotation	number	否	0	旋轉角度（度）
strokeWeight	number	否	1	線的粗細
strokes	color	否		線的顏色
strokeCap	string	否	"NONE"	線的端點樣式：NONE、ROUND、SQUARE、ARROW_LINES、ARROW_EQUILATERAL
name	string	否	"Line"	節點名稱
parentId	string	否		父節點 ID

figma_create_frame

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

參數	類型	是否必需	默認值	描述
x	number	否	0	X 座標位置
y	number	否	0	Y 座標位置
width	number	否	100	寬度
height	number	否	100	高度
name	string	否	"Frame"	節點名稱
fills	color	否		填充顏色
parentId	string	否		父節點 ID

figma_create_text

創建一個文本節點。

參數	類型	是否必需	默認值	描述
x	number	否	0	X 座標位置
y	number	否	0	Y 座標位置
text	string	否	"Text"	文本內容
fontSize	number	否	16	字體大小
fontFamily	string	否	"Inter"	字體家族
fontStyle	string	否	"Regular"	字體樣式
fills	color	否		文本顏色
name	string	否	"Text"	節點名稱
parentId	string	否		父節點 ID

figma_clone_nodes

克隆（複製）節點。

參數	類型	是否必需	默認值	描述
nodeIds	string[]	是		要克隆的節點 ID 數組
parentId	string	否		克隆節點的父節點
offset.x	number	否	20	相對於原始節點的 X 偏移量
offset.y	number	否	20	相對於原始節點的 Y 偏移量

figma_create_component

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

參數	類型	是否必需	默認值	描述
fromNodeId	string	否		將現有節點轉換為組件
x	number	否	0	X 座標位置
y	number	否	0	Y 座標位置
width	number	否	100	寬度
height	number	否	100	高度
name	string	否	"Component"	組件名稱
fills	color	否		填充顏色
parentId	string	否		父節點 ID
description	string	否		組件描述

figma_create_instance

創建一個組件的實例。

參數	類型	是否必需	描述
componentId	string	是	要實例化的組件 ID
x	number	否	X 座標位置
y	number	否	Y 座標位置
parentId	string	否	父節點 ID
name	string	否	實例名稱

💅 樣式命令

figma_set_fills

設置節點的填充顏色。

參數	類型	是否必需	描述
nodeId	string	是	要修改的節點 ID
fills	color	是	填充顏色

顏色格式：

• 十六進制：{ 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

設置節點的描邊顏色。

參數	類型	是否必需	描述
nodeId	string	是	要修改的節點 ID
strokes	color	是	描邊顏色
strokeWeight	number	否	描邊粗細（像素）

figma_set_text

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

參數	類型	是否必需	描述
nodeId	string	是	要修改的文本節點 ID
text	string	是	新的文本內容

figma_set_opacity

設置節點的透明度。

參數	類型	是否必需	描述
nodeId	string	是	要修改的節點 ID
opacity	number	是	透明度（0 - 1）

figma_set_corner_radius

設置節點的圓角半徑。

參數	類型	是否必需	描述
nodeId	string	是	要修改的節點 ID
radius	number	否	所有角的統一圓角半徑
topLeft	number	否	左上角的圓角半徑
topRight	number	否	右上角的圓角半徑
bottomLeft	number	否	左下角的圓角半徑
bottomRight	number	否	右下角的圓角半徑

figma_set_effects

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

參數	類型	是否必需	描述
nodeId	string	是	要修改的節點 ID
effects	array	是	效果對象數組

陰影效果：

{
  "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

將本地樣式應用到節點。

參數	類型	是否必需	描述
nodeId	string	是	要應用樣式的節點 ID
styleId	string	是	樣式 ID
property	string	是	屬性：fills、strokes、text、effects、grid

figma_set_variable

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

參數	類型	是否必需	描述
variableId	string	是	變量 ID
modeId	string	否	模式 ID（用於設置值）
value	any	否	要設置的值
nodeId	string	否	節點 ID（用於綁定）
field	string	否	要綁定的字段（opacity、cornerRadius、fills 等）
paintIndex	number	否	填充/描邊的繪製數組索引（默認 0）

📐 佈局命令

figma_set_auto_layout

配置框架的自動佈局。

參數	類型	是否必需	描述
nodeId	string	是	要配置的框架 ID
layoutMode	string	否	NONE、HORIZONTAL、VERTICAL
primaryAxisSizingMode	string	否	FIXED、AUTO
counterAxisSizingMode	string	否	FIXED、AUTO
primaryAxisAlignItems	string	否	MIN、CENTER、MAX、SPACE_BETWEEN
counterAxisAlignItems	string	否	MIN、CENTER、MAX、BASELINE
paddingTop	number	否	頂部內邊距
paddingRight	number	否	右側內邊距
paddingBottom	number	否	底部內邊距
paddingLeft	number	否	左側內邊距
itemSpacing	number	否	項目之間的間距
counterAxisSpacing	number	否	換行時行與行之間的間距
layoutWrap	string	否	NO_WRAP、WRAP

figma_set_layout_align

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

參數	類型	是否必需	描述
nodeId	string	是	要修改的子節點 ID
layoutAlign	string	否	MIN、CENTER、MAX、STRETCH、INHERIT
layoutGrow	number	否	增長因子（0 - 1）
layoutPositioning	string	否	AUTO、ABSOLUTE

🚚 轉換命令

figma_move_nodes

將節點移動到新的位置。

參數	類型	是否必需	描述
nodeIds	string[]	是	要移動的節點 ID 數組
x	number	否	X 座標位置或偏移量
y	number	否	Y 座標位置或偏移量
relative	boolean	否	如果為 true，x/y 為偏移量（默認 false）

figma_resize_nodes

調整節點的大小。

參數	類型	是否必需	描述
nodeIds	string[]	是	要調整大小的節點 ID 數組
width	number	否	新的寬度
height	number	否	新的高度

figma_delete_nodes

刪除節點。

參數	類型	是否必需	描述
nodeIds	string[]	是	要刪除的節點 ID 數組

figma_group_nodes

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

參數	類型	是否必需	默認值	描述
nodeIds	string[]	是		要組合的節點 ID 數組
name	string	否	"Group"	組的名稱

figma_ungroup_nodes

將組節點解組。

參數	類型	是否必需	描述
nodeIds	string[]	是	要解組的組節點 ID 數組

figma_rename_node

重命名節點。

參數	類型	是否必需	描述
nodeId	string	否	單個節點 ID
nodeIds	string[]	否	批量節點 ID 數組
name	string	是	新的名稱

figma_reorder_node

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

參數	類型	是否必需	描述
nodeId	string	是	要重新排序的節點 ID
position	string/number	是	"front"、"back" 或索引數字

figma_set_constraints

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

參數	類型	是否必需	描述
nodeId	string	是	要配置的節點 ID
horizontal	string	否	MIN、CENTER、MAX、STRETCH、SCALE
vertical	string	否	MIN、CENTER、MAX、STRETCH、SCALE

🧭 導航命令

figma_set_selection

設置當前的選擇內容。

參數	類型	是否必需	描述
nodeIds	string[]	是	要選擇的節點 ID 數組（為空則清除選擇）

figma_set_current_page

切換到不同的頁面。

參數	類型	是否必需	描述
pageId	string	是	要切換到的頁面 ID

📤 導出命令

figma_export_node

將節點導出為圖像。

參數	類型	是否必需	默認值	描述
nodeId	string	是		要導出的節點 ID
format	string	否	"PNG"	導出格式：PNG、SVG、JPG、PDF
scale	number	否	1	導出比例（1 表示 100%）

返回 base64 編碼的數據。

🧩 組件命令

figma_detach_instance

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

參數	類型	是否必需	描述
nodeId	string	是	要分離的實例 ID

🔍 令牌優化

變量查詢

建議使用 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 參數：

參數	類型	默認值	描述
namePattern	string		通配符模式（* 表示任意字符）
type	string	"ALL"	變量類型過濾器
collectionName	string		集合名稱過濾器
compact	boolean	true	最少的數據（僅包含 ID、名稱、值）
limit	number	50	最大結果數

節點遍歷

在 figma_get_nodes 中使用 depth 參數：

深度	屬性數量	使用場景
minimal	~5	樹遍歷、查找節點
compact	~10	佈局檢查
full	~40	詳細的節點編輯

查找節點

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

// 在頁面/框架內按名稱查找節點
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' })

工具	使用場景	令牌效率
figma_search_nodes	按名稱查找框架/元素	每個節點約 50 個令牌
figma_get_children	逐層瀏覽層次結構	每個節點約 50 個令牌
figma_search_components	按名稱查找特定組件	每個結果約 50 個令牌
figma_search_styles	按名稱查找特定樣式	每個結果約 30 個令牌

❗ 已知限制

• 插件代碼中不支持 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 許可證。