Figwright：使 AI 直接驱动 Figma 画布的双向工具

Figwright 借助本地 WebSocket 协议，将 MCP server 与 Figma 插件无缝对接，使 Claude Code、Cursor 等 AI agent 的功能不再局限于单纯查看 Figma 设计界面，而是能够直接在画布上执行编辑和修改等操作。

Figwright：让 AI 直接驱动 Figma 画布的双向工具

一句话先说清

Figwright 通过本地 WebSocket 中转机制，将 MCP server 与 Figma 插件相连，使得 Claude Code、Cursor 这类 AI agent 不仅能够「查看」Figma 内容，更能直接「修改」Figma 画布。

官方用一句话精准概括：Playwright 驱动浏览器，Figwright 驱动 Figma。名称源自于此，-wright 在英语中意为「匠人、制造者」（类似 playwright 写戏、shipwright 造船），Figwright 即「造设计的匠人」。

它解决什么问题

若使用过 Figma 官方的 Dev Mode MCP，通常会遇到两个问题：其一是需付费购买 Dev Mode seat，门槛较高；其二是仅支持读取无法写入，agent 虽可依据设计生成代码，却无法将代码或描述反向转化为 Figma 画面。

Figwright 绕开了这两个限制：

1. 免费使用，通过插件通道运行，免费版 Figma 即可操作，无需 Dev Mode 或任何付费席位。
2. 双向操作，总计 101 个工具涵盖读取与写入功能。agent 既可依照设计编写代码，也可根据代码或描述直接在画布上搭建图形。

此外，其代码生成并非「通用化」模式。许多 Figma 转 Code 工具输出的是一堆通用 div 和硬编码颜色，需要开发者重写。Figwright 会先探测项目实际的技术栈（框架和样式系统），然后复用已有组件、token 和图标，仅补充缺失部分。

它怎么工作

采用三层结构，全部运行在本地机器上。

最上层是 MCP 客户端，每个 agent 对应一个（如 Claude Code、Cursor 等），通过 stdio 走 MCP 协议。

中间层是 @figwright/mcp 这个 server，由客户端启动。值得关注的是其支持多客户端共享：多个 server 会自动选举一个 leader 持有唯一的插件连接，其他 follower 通过 HTTP /rpc 转发调用。当 leader 退出时，follower 自动接管，断线也能续连。该设计确保同时运行多个 agent 时不会产生冲突。

最下层是 Figma，支持桌面版或浏览器版。Figwright 插件（基于 Vue 3 编写的 iframe）运行在其中，接收 server 发来的调用，执行真正的 Figma Plugin API。

MCP 客户端 (Claude Code / Cursor) │MCP over stdio ▼@figwright/mcp(leader 选主 + 断线续传) │本地 WebSocket + msgpack ▼Figma 插件→Canvas 画布

传输走本地 127.0.0.1，不联网不出本机，数据也不外发。

插件不是黑盒

这一点做得比较用心。插件界面包含四个标签：

1. Activity，列出每一次工具调用，附带耗时信息。
2. Payload，展示发送给模型的原始数据，让用户看到 agent 究竟获取了什么。
3. Context，显示当前文件、页面和选中内容。
4. Debug，展示连接健康度，还可一键导出诊断包。

换言之，agent 背后执行的操作和使用的数据全程可见，这对调试和建立信任都很有帮助。

怎么装

分为四步，按官方顺序呈现如下。

1. 配置 MCP server。在 Claude Code 的 .mcp.json 中添加：

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

npx 会自动拉取发布版，无需全局安装。

2. 安装 Figma 插件。该插件尚未上架 Figma Community 市场，需从 GitHub Release 手动安装。下载最新 Release 的 zip 包并解压，在 Figma 桌面版中依次选择 Menu → Plugins → Development → Import plugin from manifest…，选中解压后的 manifest.json。

3. 连接。在 Figma 中打开 Figwright 插件（Plugins → Development → Figwright），它将自动连接本地 server 并显示 Connected。让 agent 运行 ping 确认链路通畅。

4.（可选）安装 skill。skill 能让 agent 在恰当时机主动调用 Figwright：

npx skills add awdr74100/figwright/skills

环境要求：一个 MCP 客户端、Node.js 24 LTS 或更新版本、Figma（免费版即可，但安装插件需桌面版）。

两个核心工作流

Figwright 的核心理念是 provider-first：不提供一套固定编译流水线，而是将真实的设计上下文完整交给模型，使其生成贴合使用者代码库的代码。这一思路被编码进两个 skill 中。

Figma → 代码（figma-codegen）

将选中的设计转换成「看起来属于这个项目」的代码，而非通用模板。核心依靠四个 grounding 工具，模型通过这些工具获取真实数据，而非依赖截图猜测：

1. get_design_context，获取结构树，将 token 解析为名称（如 Primary/500、spacing/4），对样式进行去重，每个实例附带 mainComponent 和属性。这是布局和绑定的真实数据来源。
2. component_map，将 Figma 组件映射到本地代码中的组件，提供 high/medium/low/unmapped 四档状态。high 和 medium 直接复用导入，避免重复创建。
3. token_map，将 Figma 变量映射到项目 token，映射成功后引用 candidate.ref（例如 bg-primary-500），不使用解析出的原始 hex 值。
4. 导出 grounding 无法直接处理的素材，如 logo、图片、图标等，若缺失像素信息会渲染为灰块。

此流程的硬性规则是：每个 px、每个颜色、每个圆角、每个间距，都必须从 get_design_context 获取，不能靠截图估算。截图仅代表视觉意图。另一条规则是「复用优先于重造」，只要 component_map 标明可复用，就必须导入使用，不能自行命名创建新组件。

设计变更后，design_diff 会将同一节点存储为基线（存放在 .figwright/snapshots/），下次进行 diff 时返回逐节点、逐属性的增删改情况，开发者只需修改受影响的代码，无需整屏重新生成。

代码 → Figma（figma-build）

反向流程，将代码或描述转换为 Figma 中「看起来本来就属于这个文件」的设计。同样遵循复用优先原则：先通过 get_variable_defs、scan_components、get_styles 了解文件已有的设计系统，可复用的组件使用 create_instance，颜色通过 bind_variable_to_paint 处理，标量走 bind_variable_to_node，共享样式走 apply_style_to_node，避免硬编码 hex 和 px。

使用场景

将上述能力转化为具体可执行的任务：

1. 设计还原代码并反复同步。设计师修改一版后，开发者无需从头切图，agent 运行 design_diff 仅更新变化部分。这是最日常、最高频的应用场景。

2. 代码反向输出设计稿。已有 React/Vue 组件时，产品方希望在 Figma 中查看效果以便评审或展示给客户。figma-build 将组件推送到 Figma，复用文件中已有的组件库，生成的画面与现有设计体系保持一致。

3. 批量搭建图形。101 个工具中包含 batch 工具，可一次性应用大量编辑操作。根据 spec 批量生成落地页、定价区域或整套界面，agent 能在画布上直接搭建。

4. 跨 agent 协作。团队成员可同时使用 Claude Code 连接同一个 Figma 文件，leader/follower 选主机制确保互不冲突，先使用者成为 leader。

5. 代码生成时复用真实技术栈。团队使用 Tailwind 加自有组件库时，Figwright 检测到后生成的代码直接引用现有组件和 token，而非输出需要重写的通用标签。

可能踩的坑

官方 FAQ 写得比较实在，挑两个最容易遇到的问题说明。

command not found 或 -32000 Connection closed。根本原因是 MCP 客户端启动 server 时直接 spawn 命令，不走交互 shell，因此 shell 中的 PATH、版本管理器（fnm/nvm/asdf/volta）配置均无法获取。两种解决方式：一是使用绝对路径，通过 which npx 获取完整路径填入 command 字段；二是将包装成本地依赖并去掉 @latest（@latest 会强制每次启动时从 registry 拉取一次，在 spawn 环境中容易卡住或失败）。

插件一直显示 Waiting 无法连接。server 由 MCP 客户端启动，客户端关闭后 server 即停止。需确认客户端正在运行、插件在同一个 Figma 且同一台机器上（中转走本地 127.0.0.1）、本地回环未被防火墙拦截。

和 Figma 官方 Dev Mode MCP 的取舍

若团队已全员购买 Figma 付费版，且仅需「看设计写代码」这一单向功能，官方 Dev Mode MCP 更为便捷，安装插件即可使用。

Figwright 更适合以下情况：不想为 Dev Mode 付费，或需要双向操作（既读又写），或希望代码生成强贴合已有技术栈和组件库，或想自行 fork 修改工作流（它开源，skill 可安装可修改）。其代价是需要手动安装插件、配置 MCP、理解 leader/follower 机制，初期上手比官方方案稍重一些。

几句总结

Figwright 的核心价值体现在两方面：将 AI agent 与 Figma 的只读关系升级为双向读写，同时以 provider-first 方式确保生成产物真正融入项目代码库。若需让 AI 深度参与设计到代码的循环且规避 Figma 付费限制，此工具值得尝试。