Figwright：Figma ↔ 代码双向同步的免费 MCP！Cursor 一句话改设计稿，Figma Dev Mode 钱省了

开篇：Figma 到代码这条路，终于有了"免费 + 双向"的答案

前端开发者都懂这个痛：

• 设计师在 Figma 画了个卡片，你照着写 CSS，像素眼瞅半小时；

• 官方 Figma Dev Mode MCP 是好用，但要付费席位，小团队根本不批；

• 第三方插件要么只读、要么生成一坨 <div class="div1"> 没人要的垃圾；

• 想反过来——从代码改设计稿——基本无解。

最近挖到一个新项目 Figwright，2026 年 6 月刚上线，把我这几件事一次性治了：

免费、双向、112 个 MCP 工具，让 Claude Code / Cursor / Codex 既能把 Figma 选区变成你项目里的真实组件，也能从代码直接在画布上建 Frame、写文字、改 Auto Layout、改变量。

最关键一点：不需要 Figma Dev Mode 付费席位，免费版就能用。

这篇是我在 Windows + Cursor 上实测的完整使用指南，照着抄 10 分钟跑通。

---

目录

1. Figwright 是什么

2. 为什么值得装：和官方 Dev Mode MCP 对比

3. 工作原理：MCP Server + Figma Plugin 本地 WebSocket

4. Windows 安装五步走

5. 实操 1：把 Figma 选区变成 React 组件

6. 实操 2：从代码/Spec 直接建设计稿

7. 112 个工具都能干嘛

8. Provider-first：复用你项目里的组件和 Token

9. 安全模型：为什么能放心用

10. 常见坑和解决方案

11. 适合谁 / 不适合谁

---

一、Figwright 是什么

按官方 README 的说法：

Where Playwright drives the browser, Figwright drives Figma.

Figwright 把 MCP Server 和 Figma 插件通过本地 WebSocket 连起来。任何 MCP 客户端——Claude Code、Cursor、Codex、Claude Desktop——都可以：

• 读：把 Figma 选区变成框架感知代码（layout、typography、variables、components 全部识别）；

• 写：直接创建/编辑 Frame、Text、Auto Layout、样式、变量、组件、整屏页面；

• 看：截图、PDF 导出、Motion 动画导出 MP4/GIF/WebM。

代码到 Figma 的反向流程也是官方一等公民：

所有东西都在你本机跑，不通过 Figma 云，也不需要 Dev Mode。

---

二、为什么值得装：和官方 Dev Mode MCP 对比

维度	Figwright	官方 Figma Dev Mode MCP
价格	免费 MIT	需要付费 Dev Mode 席位
方向	双向（读 + 写）	主要偏读（代码生成）
工具数量	112	数十个
代码生成策略	Provider-first，识别你项目的组件/Tokens	通用 HTML/CSS
多 Agent 共用一个插件	✅ Leader/Follower 选举	❌
数据出本机	否（127.0.0.1）	走 Figma 云
写画布（建 Frame、改变量）	✅	❌
FigJam 支持	部分（frames/shapes/text）	受限
动图导出 MP4/GIF	✅	❌

一句话：Figma 官方方案是"付费、读为主、云端"，Figwright 是"免费、读写双向、本地"。

---

三、工作原理：MCP Server + Figma Plugin 本地 WebSocket

整个链路是这样的：

MCP 客户端 (Claude Code/Cursor/Codex)
        │  MCP over stdio
        ▼
@figwright/mcp 服务器  ← npx 启动，多个客户端选举 leader
        │  本地 WebSocket 127.0.0.1:3055 (msgpack 二进制)
        ▼
Figma 插件 (Vue 3 iframe + sandbox)
        │  Figma Plugin API
        ▼
   Figma 画布

几个巧妙设计：

1. 多客户端共享一个插件连接：多个 AI 工具同时开着，自动选主，主挂了从顶上。

2. 断线恢复：WebSocket 抖了自动重连，"busy ≠ dead"心跳区分。

3. 插件面板完全透明：每一次 MCP 调用都在插件 UI 里列出来，你能看到发给模型的完整 payload。

        

面板有三个 Tab：

• Activity：每次调用，耗时、动了哪些节点、一键跳转；

• Payload：发给模型的完整 JSON，审查 AI 到底看到了什么；

• Debug：连接状态、版本、一键诊断包。

支持 Figma 浅色/深色主题自适应：

窗口大小能拖，记住尺寸；不用时可以后台运行，连接保持：

四、Windows 安装五步走

4.1 前置

• Node.js 20.19+ 或 22.12+（不支持 18/21/22.0-22.11）

• Figma 桌面版（导入开发插件必须用桌面版，浏览器版后续可连）

• 一个 MCP 客户端：Claude Code、Cursor、Codex 任选

验证 Node：

node --version
npm --version

4.2 在 MCP 客户端加配置

以 Claude Code 为例，项目根目录建 .mcp.json：

{
  "mcpServers": {
    "figwright": {
      "command": "npx",
      "args": ["-y", "@figwright/mcp@latest"]
    }
  }
}

Cursor：Settings → MCP → Add new server，填同样的 command/args。

4.3 安装 Figma 插件

插件还没上架 Figma Community，需要从 GitHub Release 手动导入：

1. 去 https://github.com/awdr74100/figwright/releases/latest 下载 figwright-plugin.zip；

2. 解压到一个固定目录，比如 D:\figma-plugins\figwright\；

3. 打开 Figma 桌面版；

4. 菜单 Plugins → Development → Import plugin from manifest…；

5. 选中解压目录里的 manifest.json。

4.4 启动并连接

1. Figma 菜单 Plugins → Development → Figwright，打开插件；

2. 插件显示 Connected 就 OK；

3. 回到 Claude Code / Cursor，让 AI 跑一下 ping 确认：

用 figwright ping 一下，看插件是否在线。

4.5（可选）装 Skills 让 AI 更聪明

npx skills add awdr74100/figwright/skills

这会装两个 skill：

• figma-codegen：把选区变成代码；

• figma-build：从代码/描述构建设计稿。

Skill 会在合适的时机自动触发，不用每次手动喊"用 Figwright"。

---

五、实操 1：把 Figma 选区变成 React 组件

5.1 基础用法

在 Figma 里选中一个卡片 Frame，切到 Cursor/Claude Code：

用 figwright 把当前选区做成一个 React 组件，用 TypeScript + CSS Modules，按钮用项目里已有的 Button 组件。

AI 会：

1. 调用 get_design_context 拉选区完整信息（去重后的 layout、字体、变量、组件）；

2. 调 component_map、token_map、icon_map 对齐你项目里的现有资产；

3. 生成 .tsx + .module.css，复用你已有的 Button、设计 token 和图标；

4. 不会生成 <div class="div1"> 这种垃圾。

5.2 不同框架

直接告诉它你的栈：

• Vue 3 + Element Plus；

• Angular + Material；

• Svelte + Tailwind；

• 小程序 + Taro。

5.3 批量导出

选中一个页面里多个卡片：

这一页所有卡片做成一个组件列表，数据从 mock 数组读。

5.4 截图 + 代码同时给

把当前选区截图，然后基于它写代码。

screenshot 工具会导出 PNG，AI 看图 + 看结构数据，比单纯看 DOM 树准确得多。

---

六、实操 2：从代码/Spec 直接建设计稿

这是 Figwright 最炸的功能，也是官方 Dev Mode MCP 没有的。

6.1 一句话建屏

在 Claude Code 里：

用 figwright 在当前 Figma 文件新建一个 Frame，1440 宽，做一个定价页： 顶部 Logo + 导航，中间三档价格卡（月付/年付切换），底部 FAQ 和 CTA。 用我们项目里的 design tokens，主色 --color-primary、字体 Inter。

AI 会：

1. 调用 create_frame、create_text、create_rectangle；

2. 用 apply_auto_layout 设好约束、间距、padding；

3. 用 set_variable / set_effect 绑定样式；

4. 整屏直接画在 Figma 画布上。

6.2 改现有设计

把选中的卡片标题改成"Pro 版"，价格改成 $29/月，按钮换成主色填充。

AI 直接改节点，不用你手动点。

6.3 批量 variant

给这个按钮组件加 4 个 variant：default / hover / disabled / loading。

6.4 动效

给这个弹层加一个 200ms ease-out 的淡入动画。

Figwright 能写 Motion 关键帧、动画预设、时间轴，最后还能导出 GIF/MP4 给设计评审用。

---

七、112 个工具都能干嘛

按官方分类：

7.1 Read（读）

• 选区、文档、节点树检查；

• 样式、变量、组件、字体；

• Reactions 和 Motion 动画状态；

• 截图、PDF 导出；

• 图片填充原始资源；

• 动画帧导出 MP4 / GIF / WebM。

7.2 Write（写）

• 创建/编辑 Frame、Text、Shape；

• Auto Layout、Effect、Style；

• 变量、组件（含 boolean / text / instance swap 属性）；

• 页面、Reactions；

• Motion 动画（关键帧、预设、时间轴）；

• batch 工具批量应用多次编辑。

7.3 Grounding（接地）

• get_design_context：去重后的完整设计上下文；

• component_map / token_map / icon_map：把 Figma 数据映射到你代码库；

• design_diff：对比设计变更，告诉你哪些代码需要更新。

完整列表 MCP 客户端连接时自动列出，这是权威清单。

---

八、Provider-first：复用你项目里的组件和 Token

这是 Figwright 最不一样的设计哲学。

传统 Figma → 代码工具是"编译器"：Figma 节点 → 通用 HTML/CSS。所以你会看到 <div class="frame-123"> 这种废稿。

Figwright 是"provider-first"：

1. 先扫描你项目里的组件库、design tokens、图标；

2. 生成代码时优先复用这些已有资产；

3. 真正需要新写的才写。

比如你项目里已经有 <Button variant="primary">、tokens.primary，Figwright 会直接用，不会自己造一套 .btn-primary。

这一切通过两个 skill 实现：

• figma-codegen：代码生成时读你项目结构；

• figma-build：建稿时用你项目的 tokens。

---

九、安全模型：为什么能放心用

README 专门讲了安全设计，我归纳一下：

1. 完全本地：MCP Server stdio，WebSocket 绑 127.0.0.1:3055，数据不出去；

2. 只触达你当前打开的文件：插件用的是 Figma 公开 Plugin API，沙箱限制；

3. 双请求头校验防 DNS rebinding：

   • Host 必须是 loopback；

   • Origin 只接受插件 sandbox 握手；

4. Leader HTTP 端点需要 CORS 预检，网页无法跨域调；

5. 写工具会改你 Figma 文件，导出工具会写文件到磁盘——你 MCP 客户端的工具审批弹窗是最后一道防线，别无脑点允许。

威胁模型和漏洞汇报流程在 SECURITY.md 里，写得很认真。

---

十、常见坑和解决方案

Q1：npx 启动报 command not found

MCP 客户端是直接 spawn 进程，不读你 shell 的 PATH。用 fnm/nvm/asdf/volta 的同学最容易踩。

解决：终端 where npx（Windows）拿到绝对路径，填进 command：

{
  "mcpServers": {
    "figwright": {
      "command": "C:\Program Files\nodejs\npx.cmd",
      "args": ["-y", "@figwright/mcp@latest"]
    }
  }
}

Q2：-32000 Connection closed，npx 跑起来立刻断

npx -y @figwright/mcp@latest 每次启动都要拉 npm，网络不通直接死。两种修法：

方法 A（推荐）：项目依赖

npm i -D @figwright/mcp

{ "mcpServers": { "figwright": { "command": "npx", "args": ["-y", "@figwright/mcp"] } } }

去掉 @latest，npx 直接用本地 node_modules。

方法 B：全局装

npm i -g @figwright/mcp
where figwright-mcp

然后 command 直接填 figwright-mcp 的完整路径，不用 npx。

Q3：插件一直 "Waiting"，连不上

检查三件事：

1. MCP 客户端是否在跑、Figwright 配置是否生效；

2. 插件是不是在同一台机器的同一个 Figma App 里打开（不支持远程）；

3. 防火墙/安全软件有没有拦 127.0.0.1:3055。

Q4：我需要付费 Figma 吗？

不需要。 免费版就够。Dev Mode 席位也不需要。

Q5：在 Dev Mode / FigJam 里能用吗？

• Figma Design：全部 112 个工具；

• Dev Mode（Inspect）：Figma 限制插件只读，写操作会失败（截图/PDF/检查都能用）；

• FigJam：frames / sections / shapes / text 能用，组件/变量/Motion 不存在。

工具失败会明确告诉你是编辑器限制，AI 会自动调整方案，不会乱重试。

Q6：多个 AI 客户端能同时用吗？

可以。多个 MCP Server 共享一个插件，自动选主，主挂了从接管。

Q7：公司禁用了 Figma 云同步怎么办？

Figwright 不通过 Figma 云通信，所有数据在本地。但插件本身需要通过 Figma 桌面版加载，如果公司完全封 Figma，就没办法了。

---

十一、适合谁 / 不适合谁

✅ 适合

• 前端工程师，天天要把 Figma 稿写成 React/Vue 组件；

• 小团队/独立开发者，不想为 Dev Mode 席位付费；

• 想让 AI 帮忙构建设计稿（产品 MVP、落地页、组件原型）；

• 用 Claude Code / Cursor / Codex，工作流已经 MCP 化；

• 注重设计 token / 组件库一致性的中大型前端团队。

❌ 不适合

• 不用 Figma（用 Sketch、即时设计、MasterGo）——目前只支持 Figma；

• 重度依赖 Figma Dev Mode 已有功能的团队——Figwright 是补充不是替代；

• 完全不让 AI 动设计文件的保守团队——那别装写权限的工具。

⚠️ 安全提醒

• MCP 客户端审批弹窗要看清楚，写操作别无脑允许；

• 不要在不信任的 Figma 文件里开插件，防 prompt injection；

• 公司项目接入前先和设计师/安全团队沟通。

---

最后总结

Figwright 把"Figma ↔ 代码"这条路做成了免费、双向、本地、MCP 原生。它不追求"一键出成品代码"的噱头，而是踏踏实实地做了三件事：

1. 给 AI 完整、去重、可信赖的设计上下文；

2. 让 AI 能真正写画布，而不是只当观众；

3. 把代码生成策略交给你项目自己的组件和 token。

如果你已经在用 Claude Code 或 Cursor，又天天和 Figma 打交道，这 10 分钟的安装时间绝对值得。

项目地址：https://github.com/awdr74100/figwright NPM：https://www.npmjs.com/package/@figwright/mcp

下一篇我准备写"用 Figwright + Claude Code 把 Element Plus 组件反向同步到 Figma 库"，想看的点个关注。