JinDaGe - figma-mcp-bridge MCP Details

article

README

🚀 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：从源代码安装

克隆仓库

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

添加到 Claude Code

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

安装 Figma 插件
- 在 Figma 中，选择 插件 → 开发 → 从清单导入插件。
- 选择克隆仓库中的 plugin/manifest.json 文件。
连接

打开一个 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 秒

🛠️ 故障排除

插件无法连接

确保 MCP 服务器正在运行。
检查端口：默认端口为 3055，或设置 FIGMA_BRIDGE_PORT。
在 Figma 中重启插件。
点击插件 UI 中的“重新连接”按钮。

端口已被使用

服务器会自动尝试 3055 - 3070 之间的端口。若要使用特定端口，请执行以下命令：

FIGMA_BRIDGE_PORT=3057 node src/index.js

多个 Claude Code 实例

每个 Claude Code 实例可以通过使用不同的端口与不同的 Figma 文件配合使用：

第一个实例：使用默认端口 3055。
第二个实例：设置 FIGMA_BRIDGE_PORT=3056。
在 Figma 插件中：在插件 UI 中更改端口号以匹配。

插件 UI 中有一个端口输入字段，可通过更改该字段连接到不同的 MCP 服务器。

命令超时

命令的超时时间为 30 秒。
大型导出可能会超时，请尝试较小的导出比例。
检查插件是否仍处于连接状态（绿色状态）。

字体错误

文本操作需要加载字体。插件会自动处理此问题，但如果字体未安装，操作将失败。请使用系统中可用的字体。

📄 许可证

本项目采用 MIT 许可证。

figma-mcp-bridge

README

🚀 Figma MCP Bridge

✨ 主要特性

🏗️ 架构

🚀 快速开始

🔍 前提条件

📦 安装

选项 A：从 npm 安装（推荐）

选项 B：从源代码安装

⚙️ 配置

🌐 环境变量

✅ 自动批准 Figma 工具

📄 命令参考

🔍 查询命令

figma_get_context

figma_list_pages

figma_get_nodes

figma_get_local_styles

figma_get_local_variables

figma_get_children

figma_search_nodes

figma_search_components

figma_search_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

figma_set_strokes

figma_set_text

figma_set_opacity

figma_set_corner_radius

figma_set_effects

figma_apply_style

figma_set_variable