与 Figma 的 MCP 对话

该项目实现了 AI 助手（Cursor、Claude Code）与 Figma 之间的模型上下文协议 (MCP) 集成，使 AI 助手能够与 Figma 通信，以读取设计并以编程方式对其进行修改。

https://github.com/user-attachments/assets/129a14d2-ed73-470f-9a4c-2240b2a4885c

项目结构

• src/talk_to_figma_mcp/ - 用于 Figma 集成的 TypeScript MCP 服务器
• src/cursor_mcp_plugin/ - 用于与 Cursor 通信的 Figma 插件
• src/socket.ts - 协助 MCP 服务器与 Figma 插件之间通信的 WebSocket 服务器

使用方法

1. 如果尚未安装 Bun，请先安装：

curl -fsSL https://bun.sh/install | bash

2. 运行设置脚本，这也会在 Cursor 的当前项目中安装 MCP：

bun setup

3. 启动 WebSocket 服务器：

bun socket

4. 新增：从 Figma 社区页面 安装 Figma 插件，或按照本地安装步骤进行安装。

快速视频教程

视频链接

设计自动化示例

批量替换文本内容

感谢 @dusskapark 贡献的批量文本替换功能。以下是演示视频。

实例覆盖传播 另一项来自 @dusskapark 的贡献： 通过一条命令将组件实例的覆盖从源实例传播到多个目标实例。此功能在处理需要类似自定义的组件实例时，可大幅减少重复性设计工作。请查看我们的演示视频。

手动设置与安装

MCP 服务器：与 Cursor 的集成

将服务器添加到 Cursor 的 MCP 配置文件 ~/.cursor/mcp.json 中：

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bunx",
      "args": ["cursor-talk-to-figma-mcp@latest"]
    }
  }
}

WebSocket 服务器

启动 WebSocket 服务器：

bun socket

Figma 插件

1. 在 Figma 中，前往“插件”>“开发”>“新建插件”。
2. 选择“链接现有插件”。
3. 选择 src/cursor_mcp_plugin/manifest.json 文件。
4. 插件现在应出现在您的 Figma 开发插件列表中。

Windows + WSL 指南

1. 通过 PowerShell 安装 Bun：

powershell -c "irm bun.sh/install.ps1|iex"

2. 在 src/socket.ts 中取消注释主机名 0.0.0.0：

// 取消注释以允许 Windows WSL 中的连接
hostname: "0.0.0.0",

3. 启动 WebSocket：

bun socket

使用说明

1. 启动 WebSocket 服务器。
2. 将 MCP 服务器安装到 Cursor 中。
3. 打开 Figma 并运行 Cursor MCP 插件。
4. 通过使用 join_channel 命令加入频道，将插件连接到 WebSocket 服务器。
5. 使用 Cursor 通过 MCP 工具与 Figma 通信。

本地开发设置

若要进行开发，请更新 MCP 配置，使其指向您的本地目录：

{
  "mcpServers": {
    "TalkToFigma": {
      "command": "bun",
      "args": ["/path-to-repo/src/talk_to_figma_mcp/server.ts"]
    }
  }
}

MCP 工具

MCP 服务器提供以下工具来与 Figma 交互：

文档与选择

• get_document_info - 获取当前 Figma 文档的信息
• get_selection - 获取当前选区的信息
• read_my_design - 无需参数即可获取当前选区的详细节点信息
• get_node_info - 获取特定节点的详细信息
• get_nodes_info - 通过提供节点 ID 数组获取多个节点的详细信息
• set_focus - 通过选中并滚动视口将焦点设置到特定节点
• set_selections - 将选区设置为多个节点，并滚动视口以显示它们

注释

• get_annotations - 获取当前文档或特定节点中的所有注释
• set_annotation - 创建或更新支持 Markdown 的注释
• set_multiple_annotations - 高效地批量创建或更新多个注释
• scan_nodes_by_types - 扫描具有特定类型的节点（可用于查找注释目标）

原型与连接

• get_reactions - 获取带有视觉高亮动画的节点的所有原型反应
• set_default_connector - 将复制的 FigJam 连接线设置为创建连接的默认样式（必须在创建连接之前设置）
• create_connections - 根据原型流程或自定义映射，在节点之间创建 FigJam 连接线

创建元素

• create_rectangle - 创建具有位置、尺寸及可选名称的新矩形
• create_frame - 创建具有位置、尺寸及可选名称的新框架
• create_text - 创建具有可自定义字体属性的新文本节点

修改文本内容

• scan_text_nodes - 对大型设计中的文本节点进行智能分块扫描
• set_text_content - 设置单个文本节点的文本内容
• set_multiple_text_contents - 高效地批量更新多个文本节点

自动布局与间距

• set_layout_mode - 设置框架的布局模式和换行行为（无、水平、垂直）
• set_padding - 设置自动布局框架的内边距值（上、右、下、左）
• set_axis_align - 设置自动布局框架的主要轴和次轴对齐方式
• set_layout_sizing - 设置自动布局框架的水平和垂直尺寸模式（固定、包裹、填充）
• set_item_spacing - 设置自动布局框架中子元素之间的距离

样式

• set_fill_color - 设置节点的填充颜色（RGBA）
• set_stroke_color - 设置节点的笔触颜色和宽度
• set_corner_radius - 设置节点的圆角半径，可单独控制每个角

布局与组织

• move_node - 将节点移动到新位置
• resize_node - 用新尺寸调整节点大小
• delete_node - 删除节点
• delete_multiple_nodes - 高效地一次删除多个节点
• clone_node - 创建现有节点的副本，可选择偏移位置

组件与样式

• get_styles - 获取本地样式的信息
• get_local_components - 获取本地组件的信息
• create_component_instance - 创建组件实例
• get_instance_overrides - 从选定的组件实例中提取覆盖属性
• set_instance_overrides - 将提取的覆盖应用到目标实例

导出与高级功能

• export_node_as_image - 将节点导出为图像（PNG、JPG、SVG 或 PDF）——目前图像导出支持有限，返回的是 Base64 编码的文本。

连接管理

• join_channel - 加入特定通道以与 Figma 通信

MCP 提示

MCP 服务器包含多个辅助提示，用于指导您完成复杂的设计任务：

• design_strategy - 使用 Figma 设计的最佳实践
• read_design_strategy - 阅读 Figma 设计的最佳实践
• text_replacement_strategy - 在 Figma 设计中系统性替换文本的方法
• annotation_conversion_strategy - 将手动标注转换为 Figma 原生标注的策略
• swap_overrides_instances - 在 Figma 中将覆盖属性在组件实例之间转移的策略
• reaction_to_connector_strategy - 利用 get_reactions 的输出将 Figma 原型中的交互转换为连接线，并指导按顺序使用 create_connections 的策略

开发

构建 Figma 插件

1. 导航到 Figma 插件目录：

   cd src/cursor_mcp_plugin
   

2. 编辑 code.js 和 ui.html

最佳实践

在使用 Figma MCP 时：

1. 发送命令前务必加入频道。

2. 首先使用 get_document_info 获取文档概览。

3. 在进行修改前，使用 get_selection 检查当前选中内容。

4. 根据需求使用合适的创建工具：

   • 使用 create_frame 创建容器；
   • 使用 create_rectangle 创建基本形状；
   • 使用 create_text 创建文本元素。

5. 使用 get_node_info 验证更改。

6. 尽可能使用组件实例以保持一致性。

7. 所有命令都可能抛出异常，因此需妥善处理错误。

8. 对于大型设计：

   • 在 scan_text_nodes 中使用分块参数；
   • 通过 WebSocket 更新监控进度；
   • 实现适当的错误处理。

9. 进行文本操作时：

   • 尽量使用批量操作；
   • 考虑结构关系；
   • 通过定向导出来验证更改。

10. 转换旧版标注时：

    • 扫描文本节点以识别编号标记和描述；
    • 使用 scan_nodes_by_types 查找标注所指的 UI 元素；
    • 根据路径、名称或位置接近度将标记与目标元素匹配；
    • 使用 get_annotations 对标注进行合理分类；
    • 使用 set_multiple_annotations 分批创建原生标注；
    • 验证所有标注是否正确链接到目标元素；
    • 成功转换后删除旧版标注节点。

11. 将原型流程可视化为 FigJam 连接线：

    • 使用 get_reactions 提取原型流程；
    • 使用 set_default_connector 设置默认连接线样式；
    • 使用 create_connections 生成连接线，以清晰地映射视觉流程。

许可证

MIT

cursor-talk-to-figma-mcp 快速上手指南

本工具通过 Model Context Protocol (MCP) 实现 AI 助手（如 Cursor、Claude Code）与 Figma 的双向通信，支持读取设计稿、批量修改文本、操作组件及自动生成连接线等功能。

环境准备

• 操作系统：macOS, Linux, 或 Windows (需配合 WSL)
• 核心依赖：
  • Bun (JavaScript 运行时)
  • Cursor 编辑器 (已安装并配置好 MCP)
  • Figma 桌面端或网页版账号
• 网络要求：确保能访问 GitHub 和 Figma 社区（国内用户若访问缓慢，建议配置代理或使用加速工具）

安装步骤

1. 安装 Bun

如果尚未安装 Bun，请运行以下命令（国内用户若官方脚本超时，可尝试手动下载或使用镜像源）：

curl -fsSL https://bun.sh/install | bash

Windows + WSL 用户注意： 请在 PowerShell 中运行：

powershell -c "irm bun.sh/install.ps1|iex"

安装完成后，需编辑 src/socket.ts 文件，取消注释 hostname: "0.0.0.0" 以允许连接。

2. 初始化项目与 MCP

克隆本项目后，在根目录运行设置脚本。该脚本会自动安装依赖并将 MCP 服务注册到当前 Cursor 项目中：

bun setup

3. 启动 WebSocket 服务器

保持终端运行，启动用于连接 Figma 插件的 WebSocket 服务：

bun socket

4. 安装 Figma 插件

在 Figma 中安装配套插件以建立通信桥梁：

• 推荐方式：访问 Figma Community 页面 直接安装。
• 本地开发方式：
  1. 在 Figma 中选择 Plugins > Development > New Plugin。
  2. 选择 Link existing plugin。
  3. 指向项目中的 src/cursor_mcp_plugin/manifest.json 文件。

基本使用

完成上述安装后，按以下步骤即可开始通过 Cursor 控制 Figma：

1. 连接通道：

   • 在 Figma 中运行已安装的 "Cursor Talk to Figma MCP" 插件。
   • 在插件界面输入一个频道名称（例如 my-design），点击 join_channel 加入频道。

2. 在 Cursor 中调用：

   • 打开 Cursor 编辑器，新建对话或打开现有项目。
   • 确保 MCP 服务器已激活（通常 bun setup 后自动配置在 ~/.cursor/mcp.json）。
   • 在对话框中输入自然语言指令，例如：
     • “读取当前选中的设计元素信息” (read_my_design)
     • “将所有标题文本改为‘欢迎使用新系统’" (set_multiple_text_contents)
     • “为选中的框架创建一个红色矩形背景” (create_rectangle, set_fill_color)

3. 验证结果：

   • 观察 Figma 画布，AI 将自动执行相应的修改操作。
   • 如需查看具体节点数据，可让 AI 调用 get_node_info 获取详细参数。

提示：首次使用前，建议先让 AI 执行 get_document_info 以了解当前设计稿的整体结构。