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