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 许可证。