Figma MCP Server：让 Agent 直接读写设计稿

简介

设计师在 Figma 里画好原型，开发者要让 AI 根据设计稿生成代码——但 Agent 看不到 Figma 里的内容。Figma MCP Server 通过官方 API 让 Claude Code、Cursor、VS Code 中的 Agent 直接读取 Figma 文件的节点树、样式、组件、图层结构，自动转为代码可用的设计 Token。本文介绍 Figma MCP 的核心能力、三种客户端配置方式、三个实战场景（设计稿转组件 / 设计 Token 提取 / 多页面批量生成），以及与 Puppeteer MCP 的协作模式。

为什么 Agent 需要直接读 Figma

如果你做过"设计稿转代码"的工作，一定经历过这个痛苦循环：

设计师：这是 Figma 链接，按这个做
    ↓
你打开 Figma → 截图 → 丢给 AI → AI 瞎猜 → 不对 → 手动改 → 再截图 → 再丢给 AI
    ↓
设计师：间距不对、颜色不对、圆角不对
    ↓
你：...

问题的核心是：Agent 拿到的是截图，不是设计稿。截图丢失了所有结构化信息——节点层级、精确尺寸、样式 Token、组件引用、约束关系。AI 只能从像素猜设计意图，这就像让程序员看渲染后的 HTML 而非源代码来重构逻辑。

Figma MCP Server 解决的正是这个问题：它让 Agent 通过 Figma 官方 REST API 直接读取文件的结构化数据，包括：

节点树（Frame → Group → Component → Text 的层级关系）
精确样式（颜色、字体、间距、圆角、阴影的精确值）
组件定义（主组件与实例的引用关系）
自动布局约束（Auto Layout 的方向、间距、padding）
图层导出（直接获取 PNG/SVG/PDF 切图）

核心能力

能力	说明	示例
读取文件结构	获取 Figma 文件的完整节点树	"读取这个 Figma 文件的所有页面和 Frame"
获取节点详情	精确到每个节点的样式和属性	"获取名为 'Button-Primary' 的组件的所有样式属性"
导出图片	导出指定节点为 PNG/SVG	"导出所有图标节点为 SVG 格式"
搜索节点	按名称或类型搜索节点	"找到所有 Text 节点并提取文字内容"
获取组件库	读取已发布的组件库	"列出这个文件引用的所有外部组件"

客户端配置

方式一：Claude Code

在 ~/.claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR_FIGMA_API_KEY"],
      "env": {
        "FIGMA_API_KEY": "YOUR_FIGMA_API_KEY"
      }
    }
  }
}

获取 API Key：登录 Figma → Settings → Account → Personal access tokens → 生成新 Token（需要 File content 读取权限）。

方式二：Cursor

在 Cursor 的 Settings → MCP Servers 中添加：

{
  "figma": {
    "command": "npx",
    "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR_FIGMA_API_KEY"]
  }
}

配置完成后，在 Cursor Chat 中可以直接说"读取这个 Figma 文件：https://www.figma.com/file/xxx"，Agent 会自动调用 MCP 获取设计数据。

方式三：VS Code（Trae / CodeGPT 等）

在 VS Code 终端运行：

# 全局安装
npm install -g figma-developer-mcp

# 设置环境变量
export FIGMA_API_KEY="YOUR_FIGMA_API_KEY"

# 验证安装
npx figma-developer-mcp --help

然后在支持 MCP 的 VS Code 扩展中配置 MCP Server 地址为 figma-developer-mcp。

实战场景

场景一：设计稿转 React 组件

这是最常见的用法：给 Agent 一个 Figma 链接，让它直接生成匹配的 React 组件。

操作步骤：

在 Figma 中选中目标 Frame，右键 → Copy link to selection
在 Claude Code / Cursor 中输入：

请根据这个 Figma 设计稿生成 React + TailwindCSS 组件：
https://www.figma.com/file/ABC123/Design?node-id=42-107

要求：
1. 使用 TailwindCSS 实现样式，不要内联 style
2. 组件名用 PascalCase
3. 文字内容保留原文，不要自作主张改
4. 颜色用 Tailwind 的最接近色值，不精确时添加注释标注原始色值
5. 图标用 lucide-react

Agent 会：

调用 Figma MCP 读取 node-id=42-107 的节点树
解析每个子节点的样式（颜色、字体、间距、圆角）
将 Figma 的 Auto Layout 映射为 Flexbox
生成 React 组件代码

关键点：你给的 node-id 越精确，生成的代码越准确。选整个页面 vs 选某个 Frame，效果差别巨大。

场景二：批量提取设计 Token

设计师定义了一套设计系统，开发者需要提取为代码可用的 Token 文件。

请读取这个 Figma 文件的所有颜色样式和文字样式：
https://wwwwww.figma.com/file/ABC123/Design-System

生成两个文件：
1. tailwind.config.js 的 extend.colors 部分
2. CSS 变量格式的 design-tokens.css

颜色命名保持与 Figma 中的样式名一致。

Agent 会：

调用 MCP 获取文件中所有 paintStyles 和 textStyles
将 Figma 的 RGB 值转为 HEX
按命名生成 Tailwind 配置和 CSS 变量

场景三：多页面批量生成

一个 Figma 文件包含 10 个页面的设计稿，需要批量生成 10 个对应的组件文件。

请读取这个 Figma 文件的所有页面：
https://www.figma.com/file/ABC123/App-Design

对每个页面：
1. 读取顶层 Frame 的结构
2. 生成对应的 React 组件，文件名用 kebab-case
3. 统一放在 src/pages/ 目录下
4. 每个组件引用共享的 Button、Input、Card 组件

设计稿中用到的图标，检查是否已安装 lucide-react，未安装的用 SVG 内联。

与 Puppeteer MCP 的协作

Figma MCP 读设计稿，Puppeteer MCP 截网页——两者配合可以实现"设计稿 vs 实现"的自动对比：

1. [Figma MCP] 读取设计稿，提取预期布局和样式
2. [Agent] 生成 React 代码
3. [Puppeteer MCP] 打开本地 dev server，截取实际渲染效果
4. [Agent] 对比设计稿截图和实际截图，输出差异清单

这种"设计→生成→验证"的闭环是当前 AI 前端开发的最佳实践之一。

注意事项

问题	解决方案
API Key 权限不足	确保 Token 有 `File content: Read` 权限
大文件读取超时	指定具体的 node-id 而非整个文件
组件引用外部库	MCP 会返回外部组件的 key，需额外请求获取
图片导出限速	Figma API 限速 100 次/分钟，批量导出时加 sleep
文字内容乱码	确保文件语言设置正确，中文字体已嵌入

选型对比

MCP	适合场景	不适合
Figma MCP	设计稿转代码、设计 Token 提取	实时协作、设计修改
Puppeteer MCP	网页截图、E2E 测试	读取设计稿结构
Fetch MCP	抓取网页内容	需要 DOM 结构的场景
两者配合	设计→代码→验证闭环	—

总结

Figma MCP 的核心价值是把"设计稿"从"图片"变成了"数据"。当 Agent 能直接读取节点的精确尺寸、样式值、组件引用关系时，"设计转代码"的准确率可以从 60% 提升到 85%+。剩下 15% 的差距主要来自设计师的主观决策（如动效曲线、交互细节）——这些需要人类判断，不是工具能解决的。