grab/cursor-talk-to-figma-mcp · 上手攻略

仓库：grab/cursor-talk-to-figma-mcp
链接：https://github.com/grab/cursor-talk-to-figma-mcp
分类：skill
作者：Tom
更新：2026-07-15

一、是什么

cursor-talk-to-figma-mcp（项目名 TalkToFigma）是新加坡 Grab 团队开源的一个 MCP（Model Context Protocol）集成工具，让 AI Agent（如 Cursor、Claude Code、Codex）能够直接与 Figma 进行双向通信——AI 可以读取 Figma 设计稿内容，也可以修改 Figma 中的元素。

技术架构上由三部分组成：

src/talk_to_figma_mcp/：TypeScript MCP Server，暴露 Figma 操作工具给 AI 调用。
src/cursor_mcp_plugin/：Figma 插件，运行在 Figma 客户端内，负责实际执行操作并回传结果。
src/socket.ts：WebSocket 服务器，桥接 MCP Server 与 Figma 插件之间的通信。

本质是用自然语言驱动 Figma——你说"把按钮文字改成提交"，AI 理解后调用 MCP 工具完成修改，不需要手动在 Figma UI 里操作。

二、解决什么问题

传统设计与开发协作流程中，设计稿（.fig 文件）是一个黑箱：

设计师改稿后，工程师需要手动对照更新代码。
AI 辅助编码时，AI 看不到设计稿，只能靠工程师描述或截图。
批量替换文字/样式，比如把 50 个页面的按钮文案全部换掉，手动操作极其繁琐。

TalkToFigma 将 Figma 变成一个AI 可读写的对象，设计改稿、批量修改、样式一致性检查等都可以由 AI 自动完成，大幅减少设计与工程的来回沟通成本。

三、快速安装

前置要求

Bun（v1.x，推荐）已安装
Cursor IDE（或其他支持 MCP 的 AI 工具，如 Claude Code、Codex）
Figma 桌面客户端或 Figma 网络版

安装步骤

Step 1：安装 Bun（如未安装）

macOS/Linux：

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

Windows（PowerShell）：

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

Step 2：运行 setup

# 克隆仓库
git clone https://github.com/grab/cursor-talk-to-figma-mcp.git
cd cursor-talk-to-figma-mcp

# 运行自动安装（会同时把 MCP server 配置进 Cursor）
bun setup

Step 3：安装 Figma 插件（二选一）

方式 A — 从 Figma Community 安装（推荐）： 1. 在 Figma 中打开任意文件 2. 点击右上角 Plugins → Search Community 3. 搜索 cursor-talk-to-figma-mcp-plugin 4. 安装

方式 B — 本地开发模式： 1. 在 Figma 中点击 Plugins → Development → New Plugin 2. 选择 "Link existing plugin" 3. 选择 src/cursor_mcp_plugin/manifest.json

Step 4：启动 WebSocket 服务器

bun socket

服务器默认监听 localhost:8765。Windows + WSL 环境下需要将 src/socket.ts 中的 hostname 改为 0.0.0.0（文件中有注释掉的配置，取消注释即可）。

Step 5：在 Cursor 中配置 MCP

~/.cursor/mcp.json（bun setup 会自动写入，重复步骤如下）：

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

本地开发时改为：

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

四、核心用法

⚠️ 使用前需先在 Figma 中运行 Cursor MCP Plugin（Plugins → Development → 选择该插件），再在 AI 中发起操作。

4.1 连接与进入频道

每次使用需要先加入频道（让插件与 MCP Server 建立 WebSocket 连接）：

使用 Cursor AI：join_channel

4.2 读取设计信息

# 获取当前文档概览
get_document_info

# 获取当前选中元素信息
get_selection

# 读取选中节点的详细属性
read_my_design

# 根据节点 ID 获取特定节点信息
get_node_info(node_id="XXX:123")

# 扫描特定类型的节点（如所有 Text 节点）
scan_nodes_by_types(types=["TEXT"])

4.3 批量修改文字

# 扫描设计中的所有文本节点（自动分块处理大文件）
scan_text_nodes

# 更新单个文本节点内容
set_text_content(node_id="XXX:123", text="新文案")

# 批量更新多个文本节点
set_multiple_text_contents(updates=[
    {"node_id": "XXX:123", "text": "新文案1"},
    {"node_id": "XXX:456", "text": "新文案2"},
])

4.4 样式修改

# 修改填充色（RGBA）
set_fill_color(node_id="XXX:123", rgba={"r": 1.0, "g": 0.0, "b": 0.0, "a": 1.0})

# 修改边框颜色和宽度
set_stroke_color(node_id="XXX:123", rgba={"r": 0, "g": 0, "b": 0, "a": 1}, stroke_width=2)

# 设置圆角（可选单角控制）
set_corner_radius(node_id="XXX:123", radius=8, corner="TOP_LEFT")

# 移动节点
move_node(node_id="XXX:123", x=100, y=200)

# 调整尺寸
resize_node(node_id="XXX:123", width=300, height=200)

4.5 创建新元素

# 创建矩形
create_rectangle(x=0, y=0, width=100, height=50, name="MyRect")

# 创建 Frame（容器）
create_frame(x=0, y=0, width=375, height=812, name="iPhone Frame")

# 创建文本
create_text(x=10, y=10, text="Hello World", font_size=16, font_family="Inter")

4.6 组件实例批量覆盖

# 从源组件实例提取覆盖属性
get_instance_overrides(source_instance_id="XXX:123")

# 将提取的属性批量应用到多个目标实例
set_instance_overrides(target_instance_ids=["XXX:456", "XXX:789"], overrides={...})

4.7 标注系统

# 获取当前文档所有标注
get_annotations

# 创建/更新单个标注（支持 Markdown）
set_annotation(node_id="XXX:123", content="### 设计说明\n这是主按钮")

# 批量创建标注
set_multiple_annotations(annotations=[
    {"node_id": "XXX:1", "content": "标注1"},
    {"node_id": "XXX:2", "content": "标注2"},
])

4.8 FigJam 连接线（原型流程）

# 获取所有原型反应（带动画高亮）
get_reactions

# 设置默认连接器样式（先复制一个 FigJam 连接器，再运行此命令）
set_default_connector

# 根据反应或自定义映射批量创建连接线
create_connections(reactions_output=get_reactions_output)

五、典型使用场景

场景	推荐工具组合
设计稿审查 → 自动提取文案给 AI	`get_document_info` + `scan_text_nodes`
批量替换 50 个页面的按钮文字	`scan_text_nodes` + `set_multiple_text_contents`
将手动标注转为 Figma 原生标注	`get_annotations` + `set_annotation`
组件实例批量属性同步	`get_instance_overrides` + `set_instance_overrides`
设计稿导出为图片	`export_node_as_image`
将 Figma 反应转换为连接线	`get_reactions` + `set_default_connector` + `create_connections`

六、坑与注意

必须同时运行 WebSocket 服务器：只装 MCP 不运行 bun socket，Figma 插件无法通信，会一直显示连接失败。
Figma 插件需手动启动：不是系统级插件，每次新开 Figma 文件需从 Plugins 菜单重新运行。
WSL/Windows 特殊配置：Windows + WSL 环境下需要修改 src/socket.ts 的 hostname 为 0.0.0.0，否则连不上。
图像导出支持有限：export_node_as_image 目前导出 base64 文本（非真正的图片文件），需自行解码或二次处理。
中文文字：实测对中文支持取决于 Figma 字体是否安装，中文乱码通常是 Figma 端字体缺失，不影响 MCP 本身。
安全注意：WebSocket 服务器默认无鉴权，在公共网络使用需自行加防火墙规则。

七、与同类对比

工具	类型	侧重点
grab/cursor-talk-to-figma-mcp	MCP Server + Figma Plugin	AI Agent 驱动 Figma，读写均可
Figma REST API	官方 API	只能读，需 OAuth，权限受限
figma-js-sdk	官方 SDK	Figma Plugin 开发用，非 AI 集成
Anima/Figma plugins	设计转代码插件	单向设计→代码，不支持 AI Agent

本工具的核心差异是以 AI Agent 为中心——Figma 是 AI 的工具，而非工程师的工具。

八、一句话推荐结论

如果你已经在用 Cursor 或其他 AI 编码工具，同时团队设计交付在 Figma 里，TalkToFigma 是目前最直接的 AI ↔ Figma 双向打通方案——让 AI 直接读图、改图，而不是让工程师在中间来回截图描述。