grafta

与你的 Figma 文件对话。
获取一个 Figma 文件，然后与它对话。询问 AI 文件中有什么、修改文件，或将其转换为你使用的任意语言的代码。
无需 Figma 账号，无需运行 Figma 应用，也没有 API 限制。

试用 · 安装 · 可以问什么 · 工具 · 限制 · 常见问题 · 网站

这是什么？ 这是一个免费、开源的工具，供 Claude、Cursor、Codex 等 AI 应用使用。它通过 MCP 连接，就像 AI 应用连接工具一样。它会精准读取你电脑上的 Figma 文件，让 AI 根据真实数值进行工作，而不是凭空猜测。

什么是 .fig？ 一种 Figma 文件。在 Figma 中，选择 File → Save local copy…。也可能有人直接把文件发给你。Slides、FigJam 和 Sites 文件也适用。

适合我吗？ 如果你有一个 Figma 文件和一个 AI 应用，那就适合。设计师可以修改文件，开发者可以将其转换为代码，收到文件的人可以询问文件内容。

试用

1. 在你的 AI 应用中安装 grafta。

2. 获取一个文件：你自己的文件，或此示例，也就是上方的卡片。

3. 用文字提问：

   使用 grafta 打开 order.fig。里面有什么？

   把它改为浅色，检查对比度，然后另存为新文件。

   现在把它转换为代码。

grafta 绝不会覆盖你的文件：它会另存为新文件，并在报告完成前重新读取该文件。用 Figma 打开它即可查看。代码质量取决于你的 AI：grafta 会提供准确数值，但不会自己编写代码。

安装

位置	操作
Claude Desktop	下载 grafta.mcpb 并打开
Claude Code	/plugin install grafta --marketplace n0ss4/grafta
ChatGPT 桌面版、Codex	codex plugin marketplace add n0ss4/grafta@main && codex plugin add grafta@grafta
macOS、Linux	curl -fsSL https://raw.githubusercontent.com/n0ss4/grafta/main/install.sh | sh
Homebrew	brew install n0ss4/tap/grafta
Windows	irm https://raw.githubusercontent.com/n0ss4/grafta/main/install.ps1 | iex
npm	npx -y grafta mcp
Rust	cargo install grafta

打开 grafta.mcpb 后，Claude Desktop 会从 Settings → Extensions 安装该软件包；无需使用终端，也无需安装 Node.js。二进制文件未经签名：如果 macOS 首次运行时提示无法检查 grafta，请在 System Settings → Privacy & Security 中允许运行。 如果遇到问题，故障排查会根据你看到的情况提供帮助。

Claude Code 插件会注册服务，并教模型如何使用它。 在其他位置，只需注册一次：

claude mcp add grafta -- grafta mcp

或者，在使用 JSON 配置的客户端中：

客户端	文件	配置
Cursor	.cursor/mcp.json（或 ~/.cursor/mcp.json）	{ "mcpServers": { "grafta": { "command": "npx", "args": ["-y", "grafta", "mcp"] } } }
Windsurf	~/.codeium/windsurf/mcp_config.json	与 Cursor 相同
Claude Desktop，手动配置	claude_desktop_config.json	与 Cursor 相同
VS Code	.vscode/mcp.json	{ "servers": { "grafta": { "command": "npx", "args": ["-y", "grafta", "mcp"] } }

通过脚本、Homebrew 或 Cargo 安装 grafta 后，使用 "command": "grafta", "args": ["mcp"] 即可实现相同功能，无需 npm。

预编译版本支持 macOS（Apple 芯片和 Intel）、Linux（x86_64 和 arm64）以及 Windows（x86_64）。这是一个独立的二进制文件。我们曾在搭载 Apple 芯片的 Mac 上手动运行过；CI 中的 Linux 和 Windows 测试也全部通过。Claude Code、Cursor、VS Code、Windsurf、Codex 和 ChatGPT 桌面应用会通过 npx 启动它，这需要 Node.js 18 或更高版本。我们已测试 Claude Code 和 Claude Desktop；其他客户端的配置方式相同。网页版 ChatGPT 无法读取本地服务，因此目前还不能使用 grafta。

为什么选择 grafta

模型擅长理解设计意图并决定要构建什么，却不擅长处理二进制格式，而且会猜测数值。grafta 则恰恰相反。它提供 43 种工具，让你的模型能够打开 .fig 文件，读取其中的每个节点、颜色、变量和组件，修改文件、绘制内容以供检查，并保存可由 Figma 打开的新文件。

四款产品

同一组工具可以打开、读取、绘制并保存 Figma 保存的所有文件；我们也已在各款产品中打开对应文件进行验证。

产品	文件	grafta 支持的内容
Figma Design	.fig	屏幕、组件和变体、带模式的变量、样式、自动布局、富文本、图像、矢量
Figma Slides	.deck	网格中的幻灯片、演讲者备注、模板；移动幻灯片时会保留转场和对象动画
FigJam	.jam	便签、带文字的形状、节点间的连接线、分区、表格、印章
Figma Sites	.site	按路由组织的网站页面，每个页面包含多个断点；在断点内，每种工具的工作方式都与画框相同

查看效果

同一帧，展示三次。每张图片都是 grafta 自己的 render_node；它们之间的每次变化，都是模型会发起的一次工具调用 （共 58 次）。

草稿	设计完成	深色模式
帧和文本	9 个颜色变量、Lucide 图标、自动布局	帧上的一个属性：explicitVariableModes

模型如何使用它

结果有明确边界：如果有内容被省略，结果会在 omitted 下说明省略了什么，以及如何获取。不会悄无声息地截断内容。

可以提出哪些要求

以下提示词可以直接使用。模型会选择合适的工具。

任务	提示词	它会用到的工具
了解文件	用 grafta 打开 handoff.fig。里面有什么、如何组织，以及使用了哪些颜色和组件？	summarize、search_nodes、read_node
转换为代码	用 grafta 打开 checkout.fig。按照文件中的确切尺寸、颜色和图标，用我们的技术栈构建付款界面。	read_node、list_variables、render_node
深色模式	用 grafta 打开 app.fig。将 Settings 界面上的颜色转换为 Light 和 Dark 变量，将每个填充都绑定到这些变量，渲染两种模式，并保存为 app-dark.fig。	create_variable set_properties render_node
设计系统审查	用 grafta 打开 library.fig。列出其中的组件、变量和样式，并告诉我哪些界面使用了既不是变量也不是样式的颜色。	list_components list_variables search_nodes
无障碍检查	用 grafta 打开 checkout.fig，检查每个界面中的文本对比度是否符合 WCAG AA。使用文件自身的颜色修复未通过的项目，并向我展示修复前后的效果。	check_contrast set_properties render_node
根据数据生成界面	用 grafta 打开 shop.fig。在环绕网格中，为 products.csv 的每一行产品放置一次 Product 卡片组件，并填入每行的名称、价格和照片。	fill_template
将 HTML 转换为图层	用 grafta 将 landing page 的快照 page.json 导入 site.fig 的新页面。	import_layout
制作演示文稿	用 grafta 打开 pitch.deck。在标题页后添加三张幻灯片，展示我们的 Q3 数据；在幻灯片之间添加淡入淡出效果和演讲者备注，然后将所有幻灯片导出为一个 PDF。	duplicate_node set_properties export_pdf

功能

任务	工具
查找	open_file summarize search_nodes list_open close_file	页面、计数，以及按名称或类型查找节点，并显示其路径
读取	read_node read_raw list_components component_instances get_image	按 Figma 插件 API 中的名称精确读取节点
查看	render_node export_pdf check_contrast	将画框渲染为 PNG，包含未保存的编辑内容，并采用其变量模式；将画框导出为矢量 PDF，每页一个画框；检查每段文本与其背后所绘内容之间的 WCAG AA 对比度
绘制	create_page create_frame create_text create_shape create_vector create_instance create_section	画框、富文本、形状、SVG 图标、实例
导入	import_layout	根据浏览器生成的快照，将网页布局导入为画框、文本、图片和自动布局（见下文）
更改	set_properties override_instance move_node duplicate_node group_nodes ungroup delete_node	填充、描边、效果、自动布局、尺寸、约束、图片、顺序
设计系统	create_component create_variant_set set_variant add_component_property fill_template	组件、变体及其属性；按 JSON 或 CSV 的每一行放置一个组件
令牌	list_variables create_variable_collection create_variable set_variable set_variable_collection	带有模式（浅色、深色）的集合、别名、绑定
样式	list_styles create_style set_style	颜色、文本和效果样式
保存	new_file save_as	从空白创建新文件，或保存打开的文件及其编辑内容

所有工具及其参数都列在工具参考中，该文档根据服务自身的工具列表生成（网站上也有）；在终端中运行 grafta tool 可列出这些工具。

为何值得信赖

承诺	含义
精确	每个数值都从文件字节中读取：不使用启发式方法、模型或网络
说明省略内容	截断结果会指出缺失内容；图片会说明近似绘制的内容
不会覆盖你的文件	save_as 会拒绝覆盖已有路径，但 new_file 刚创建的空文件除外；并会重新读取写入的内容
重启后仍可恢复	未保存的编辑会在操作时记录到日志（~/.grafta/journals），并在重新打开时重放
宁可拒绝，也不破坏	如果有节点指向某个节点，就不会删除它；也不会写入 Figma 会自动修复的内容，并会说明原因

限制

• 它不会解读设计。 这由你的模型来做。grafta 会回答文件中有什么，并按指示编写内容。
• 它不是实时的，也不支持协作。 你在保存的副本上工作，然后打开它返回的新文件。要处理实时文件，请使用 Figma 自带的服务。
• 代码质量取决于你的模型。 grafta 会提供精确值，本身不会编写代码。Figma 的服务和 Framelink 也能通过 Figma 链接将设计转换为代码，但需要账户。
• 它与 Figma 无关，读取和写入其格式时不依赖 Figma。
• 它处理的是文件，而非 Figma 云端文件：Figma Design 的 .fig、Figma Slides 的 .deck、FigJam 的 .jam 和 Figma Sites 的 .site。保存本地副本，然后在 Figma 中打开结果。new_file 会从你已有的 .fig 文件中获取 Figma 格式；grafta 不会随附该文件。
• 图片效果接近，但并非 Figma 的效果。 图片使用你机器上安装的字体：如果安装了设计中使用的字体，大多数行的宽度与 Figma 相差不超过 2%；如果没有，则会使用替代字体，并在说明中注明。安装字体后重启服务。
• 打开文件会占用内存，而且占用量远大于文件大小：在一台 Mac 上，一个 57 MB 的文件打开时占用 1.3 GB 内存，一个 86 MB 的文件则占用 5.5 GB。处理完文件后请将其关闭。
• 暂不支持： 自动布局网格、组件插槽、布尔运算、原型设计、Dev Mode 注释，以及变体上的组件属性。
• 只能更改 grafta 自己的变量和样式。 文件中已有的变量和样式会被读取并绑定，但不会被编辑。

从网页导入

import_layout 会将 HTML 转换为可编辑的设计：flexbox 会根据浏览器的测量结果转换为自动布局、填充、适应内容或固定尺寸。grafta 不会运行浏览器；浏览器会对布局结果进行快照，然后由 grafta 读取。

curl -fsSLO https://n0ss4.github.io/grafta/snapshot.sh && curl -fsSLO https://n0ss4.github.io/grafta/snapshot.js
sh snapshot.sh page.html page.json 'main'     # headless Chrome; a CSS selector picks the part

或者，在任意浏览器控制台或模型的浏览器工具中，粘贴 snapshot.js，然后运行 copy(JSON.stringify(graftaSnapshot('main'))). 接着让模型导入 page.json。无法映射的内容（渐变、变换、内联 SVG、远程图片）会列出来，不会进行猜测。

从终端使用

无需模型也能使用相同的工具：

grafta tool                                     # list the tools
grafta tool read_node                           # what one takes, with an example
grafta tool open_file '{"path":"design.fig"}'   # call one: each call starts afresh
grafta tool --batch calls.json                  # a sequence on one open file

批处理内容是一个 JSON 数组，元素格式为 { "tool", "args", "out"? }；参数中的 "$0.handle" 表示调用 0 的结果字段，"out" 会将图片写入文件。展示示例 就是其中之一。

常见问题

我需要 Figma 账户或 API 密钥吗？ 不需要。grafta 会处理你磁盘上的文件。你只需使用 Figma 保存本地副本并打开结果。

我的文件会离开我的机器吗？ grafta 不会发起网络请求。模型通过它读取的内容与其他工具结果一样，会被发送到 MCP 客户端用于发送对话的目的地。

它会损坏我的文件吗？ 它不会覆盖文件：save_as 会拒绝已存在的路径，并重新读取写入的内容。它会拒绝 Figma 必须修复的内容；未保存的编辑也会在重启后保留。

支持哪些客户端和模型？ 任何通过 stdio 使用的 MCP 客户端（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf……），以及它运行的任意模型。

它与 Figma 有关联吗？ 没有。它免费且开源，采用 MIT 许可证。

参与贡献

了解它的构建方式（架构）、未来规划（路线图）以及参与开发的方法（贡献指南）。变更记录见更新日志；如需报告漏洞，请按 SECURITY 中的说明操作。

MIT 许可证。与 Figma 无关。