WorkBuddy Figma
This server bridges WorkBuddy to a local Figma plugin so you can inspect and modify Figma documents directly through the Figma Plugin API.
Check connection status, regenerate the paired plugin, and select among connected Figma documents.
Create local task/session records for a selected Figma file.
Run arbitrary Figma Plugin API JavaScript with
use_figmato read or write the canvas.Read the current selection, layer trees, metadata, design context with CSS, FigJam structure, and motion/prototype data.
Export real PNG screenshots and read component, component-set, and instance context.
Read variables, collections, team variable libraries, and search local components, variables, and styles.
Read and write local component-to-code links as Figma plugin data.
List available font families and styles.
Upload workspace raster/SVG files as editable layers or image fills.
Download/export nodes as PNG, JPG, SVG, or PDF, optionally with original image bytes.
Import JSON scenes as native editable Figma nodes.
Enables direct read/write access to Figma documents through a local companion plugin, with tools for inspecting selections and layer trees, executing Figma Plugin API scripts, managing components, variables, styles, auto layout, exporting screenshots and assets, and importing assets into the canvas.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WorkBuddy Figma 看我选中的画板,把主按钮统一改成 40px 高、8px 圆角,改完截图给我"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
workbuddy-figma
让 WorkBuddy 直接读写你的 Figma 画布。
不用 Figma 官方 MCP,不消耗 Dev Mode 配额,不是截屏点鼠标 —— 而是通过 Figma 开放的插件 API, 以本地插件的身份直接操作图层。画板、文字、组件、变量、自动布局、导出截图,全都能用。
为什么需要它
Figma 官方 MCP | 截屏 + 模拟点击 | 本项目 | |
需要付费席位 | ✅ 需要(Star 计划 / Dev Mode) | ❌ 不需要 | ❌ 不需要 |
消耗官方 MCP 额度 | ✅ 消耗 | ❌ 不消耗 | ❌ 不消耗 |
改分辨率后还能用 | ✅ | ❌ 坐标全废 | ✅ |
能改真实图层 | ✅ | ✅ 但极易点错 | ✅ |
读取图层结构 / 变量 | ✅ | ❌ 只能看图 | ✅ |
需要 Figma 桌面版 | ❌ | ✅ | ✅ |
Figma 的官方 MCP(mcp.figma.com)走 Dev Mode,免费账号进不去。
但 Figma 的插件 API 对所有账号开放 —— 只要这个文件里跑着一个本地开发插件,
它就能读能写整个文档。本项目就是把这个能力接到 WorkBuddy 上。
Related MCP server: FigmaExporterMcp
怎么工作
graph LR
A["WorkBuddy<br/>(MCP 客户端)"] -->|"JSON-RPC / stdio"| B["server.mjs<br/>本地 MCP 服务"]
B -->|"HTTP 长轮询<br/>localhost:3055 起"| C["Figma 伴生插件<br/>(跑在你的文件里)"]
C -->|"Figma Plugin API"| D[("你的 Figma 文档")]三句话:
WorkBuddy 启动时拉起
server.mjs,它是一个标准 MCP server,对外暴露 21 个工具。server.mjs在本机开一个小 HTTP 服务,等 Figma 插件来连。默认从 3055 起,被占用就自动往后顺延 (最多 10 个端口),真实端口会同步写进插件里,不需要你手动对齐。你在 Figma 里运行一次插件,两边用一对本机随机 token 配对,之后就一直通着。
配对 token 是安装时现场生成的 32 字节随机数,只存在你本机,install.mjs 会把它注入到
code.js 里。每台机器生成的插件 id 都不一样,互不干扰。
安装
前置条件
Node.js ≥ 18
WorkBuddy 桌面版
Figma 桌面版(网页版不支持导入本地开发插件)
一键安装
git clone https://github.com/kkse7en/workbuddy-figma.git
cd workbuddy-figma
node install.mjs脚本会做四件事,全程自动:
生成本机配对 token
生成已配对的 Figma 插件,并打印
manifest.json路径把 MCP server 写进
~/.workbuddy/mcp.json(原文件自动备份)如果检测到你装过 Figma 官方 MCP,会把它改名成
figma-cloud并停用,避免冲突
想先看看会改什么,加 --dry-run:
node install.mjs --dry-run换起始端口(默认从 3055 开始找空闲的):
node install.mjs --port 3060装完之后
第一步 · 重启 WorkBuddy。 MCP 配置只在启动时读一次,不重启不生效。
第二步 · 信任 MCP。 打开连接器管理,找到 figma,点「信任」。
自定义 MCP 必须手动授权,这是 WorkBuddy 的安全设计,脚本改不了。
第三步 · 让 Figma 认这个插件。 两条路,推荐第一条:
① 直接注册(推荐,跳过导入对话框)
完整退出 Figma(含托盘图标),然后:
node install.mjs --register它会把这个插件直接写进 Figma 的插件列表。重新打开 Figma,
Plugins → Development 里就会出现 workbuddy-figma,不用再选文件。
忘了关 Figma 也没关系:脚本会检测到并跳过注册(开着写进去会被 Figma 退出时覆盖), 其余步骤照常完成,最后提示你关掉 Figma 再跑一次这条命令。
为什么推荐这条:Figma 的「Import plugin from manifest」对话框在部分环境下会对 本地路径报一句
manifest.json 文件名无效,但不说哪里无效。实测同样的 manifest 换个目录就能导入,是对话框自身的问题。直接写注册表可以完全绕开。脚本会自动定位各平台的 Figma 配置:
%APPDATA%\Figma\settings.json(Windows)、~/Library/Application Support/Figma/settings.json(macOS)、~/.config/Figma/settings.json(Linux)。
② 手动导入
Plugins → Development → Import plugin from manifest…选 install.mjs 打印的那个 manifest.json,通常在:
~/Documents/workbuddy-figma-plugin/manifest.json然后在目标设计文件里运行 Plugins → Development → workbuddy-figma。
会弹出一个窄条小窗口,留着别关 —— 它一关,连接就断。
插件放在
~/Documents而不是~/.workbuddy:后者是隐藏目录, Figma 的文件选择器里不好找,部分版本还会挑路径。
验证
在 WorkBuddy 里说:
看看 Figma 连接状态
或者直接跑自检(不需要打开 Figma,会自己模拟一个插件):
node selftest.mjs看到 全部通过 ✅ 就说明桥接链路没问题。
能做什么
管理工具(3 个)
工具 | 作用 |
| 看连接状态、已连文档、插件版本。出问题先看这个 |
| 重新生成已配对的插件,返回 manifest 路径 |
| 同时连了多个文件时,指定操作哪个 |
画布工具(18 个)
工具 | 作用 |
| 在画布里直接执行 Figma Plugin API 脚本,读写都行。这是最核心的工具 |
| 读当前页和选中的节点 |
| 读图层树(带分页,别一次拉整棵树) |
| 导出真实 PNG 截图 |
| 读子树 + CSS,做设计稿转代码用 |
| 读 FigJam 结构 |
| 读设计变量 / 变量集合 |
| 搜本地组件、变量、样式 |
| 读组件、组件集、实例属性 |
| 读团队变量库 |
| 读本地组件与代码的映射 |
| 写本地组件与代码的映射 |
| 读原型交互与动效数据 |
| 查可用字体族与字重 |
| 把本地图片 / SVG 导入为可编辑图层 |
| 导出 PNG / JPG / SVG / PDF |
| 用 JSON 场景导入原生节点 |
| 建一个本地任务记录(可选) |
用法示例
连接好之后,直接说人话就行:
看看我选中的画板,把主按钮统一成 40px 高、8px 圆角,改完给我截图。
参考这个深色界面,在新画板里做一个浅色版,文字和布局保留成可编辑图层。
读一下这个画板的图层结构,在当前项目里实现成 React 页面,素材导出到 assets 目录。
给这个按钮补上 hover 和 disabled 状态,颜色绑到对应的语义变量。
把这页所有 Frame 的间距从 40 改成 24。
连接稳定性
长轮询桥最怕的不是慢,是「看起来连上了但下一次就没反应」。下面这些点都会真实造成这种症状,已逐个修掉。
症状 | 原因 | 处理 |
连着连着报 | Node 默认 | 保活提到 65s,headers 70s 同步放宽 |
一次网络抖动就永久卡住 | 旧 poll 未回收时新 poll 直接返回 409,插件端断不开 | 新 poll 接管旧 poll(旧的以 |
操作成功却被判「结果未知」 | 结果回传请求本身超时,重试被当成重复操作 |
|
同一个文件重开插件后一直超时 | 僵尸连接留在列表里,工具挑到了那条等不到响应的 | 新连接清掉同 |
跑过一次自检后插件突然 401 | 自检和日常共用状态目录,把插件的端口/token 覆写了 | 自检改用独立状态目录 + 独立插件目录 |
「一直连接中」/「配对已失效」,但桥明明在跑 | 桥只绑 | 桥改双栈监听( |
桥整个没起来,工具一直报连不上 | 早期版本设了 | 任何时候都允许顺延 10 个端口,真实端口自动写回插件 |
重装后端口莫名跳到下一个 | 安装脚本靠 401 文案判断「是不是自己的桥」,但别的 Figma 桥文案一模一样,被误认为可复用 | 桥加 |
另外客户端退避改成了 300ms 起、最多 5s(原来 1s→10s,抖动一次像断了半分钟), 401 会先用当前密钥自动复验一次再报「配对失效」, 执行中断后的按钮也从「请重新打开插件」改成了可点的「恢复连接」。
常见问题
插件一直是「连接中 / 等待桥启动」
按顺序看:
插件是不是旧目录那条?
Plugins → Development里如果出现[DEPRECATED]前缀的条目, 那是历史残留,token 对不上,点了也连不上。用不带前缀的workbuddy-figma。桥在不在跑:WorkBuddy 重启后才会拉起
server.mjs。 在终端里确认一下(有x-workbuddy-figma: 1这个响应头才是我们的桥):curl -i http://localhost:3060/health返回 401 +
x-workbuddy-figma: 1是正常的(401 只表示没带 token)。 如果连不上、或者没有这个响应头,说明端口上蹲着别人的服务。端口对不对:插件里的端口是生成时写死的。跑一次
node install.mjs, 它会重新探测空闲端口并把插件同步过去,然后重开插件窗口(不是重新导入)。
报「配对已失效」
插件里的 token 和桥的 token 不一致。常见两种原因:
你运行的不是最新生成的那份插件,或者状态目录被重新初始化过。
插件连到了另一个 Figma 桥。同端口上如果蹲着别的实现(旧版 DSH / Codex 之类), 它也会回一句
Pairing token required,但 token 不是你的 —— 表现就是「配对校验失败」。 v1.2 起桥改双栈监听 + 响应头标识,这种撞车已经能自己让开;旧版本请升级。
node install.mjs然后用它打印的 manifest.json 重新导入一次(或直接 node install.mjs --register)。
旧条目可以在 Plugins → Manage plugins 里删掉。
Figma 报「manifest.json — 文件名无效」
先别怀疑文件名。 这个提示是 Figma 那个导入对话框的通用兜底文案,实测有两种触发场景:
场景 | 处理 |
这个插件 id 已经导入过,Figma 按 id 去重 | 别重复导入,直接在 |
对话框本身挑路径(同一份 manifest 换个目录就能导入) | 绕开对话框: |
--register 会直接写 Figma 的插件列表,前提是 Figma 已完全退出 —— 否则它退出时会把整份配置覆盖回去。
端口被别的程序占了
install.mjs 会自己处理端口,通常不用你操心:
如果本项目的桥已经在跑,直接复用它的端口(重装不会把插件改到别处去)。
否则从 3055 起找第一个真的空闲的端口。判断「空闲」不只看能否 bind, 还会发一次 HTTP 确认没人在服务 —— 因为 Windows 上别的程序只占
127.0.0.1时,bind ::依然会成功,光看 bind 会把它当成空的。十个端口全被占才需要显式指定:
node install.mjs --port 3080判断端口上是不是自己的桥:
curl -i http://localhost:3055/health有 x-workbuddy-figma: 1 响应头才是本项目的桥。没有响应头就别复用这个端口,
换个端口更省事 —— 两条桥挤在同一个号上,localhost 解析到哪一边是不确定的。
版本提醒:v1.2 之前桥只绑
127.0.0.1,遇到「只占 IPv4 的邻居」时, Figma 走localhost会优先落到::1,请求就跑去别人那里了。 这类「明明在跑却一直连不上」的问题升级到这个版本即消失。
每次改完,画布都跳回第一页
插件契约规定 use_figma 每次从第一页开始。脚本里显式切页就行:
const target = figma.root.children.find(p => p.name === '你的页面名')
await figma.setCurrentPageAsync(target)报 Previous operation outcome is uncertain
上一次写操作失败后,桥接层会把文档标记为「状态不明」,防止你在未知状态上继续写。
先跑一次只读的 get_metadata 清除标记,再继续。
报 Cannot access property children on a page that has not been explicitly loaded
这个文件是 documentAccess: "dynamic-page" 模式,页面要先加载:
await page.loadAsync() // 或者 await figma.loadAllPagesAsync()WorkBuddy 里看不到 figma 工具
按顺序排查:① 重启过 WorkBuddy 吗 ② 连接器里点「信任」了吗 ③ 看 ~/.workbuddy/mcp.json
里 figma 那项对不对。
插件显示「已连接」但没反应
先关掉多余的插件窗口。同一个文件开两个插件会产生两条连接,虽然新版会自动挑最近的那条并清理 30s 内无活动的僵尸连接,但保持只有一个窗口最省事。
安全说明
配对 token 是安装时本机随机生成的 32 字节,只存在你本机,不上传任何服务器。
桥只监听回环地址(
127.0.0.1与::1,双栈是为了让 Figma 的localhost请求一定能回到自己人手上), 并且校验Origin必须是 Figma 域名,外部访问会被拒。生成的插件目录含本机凭证:默认在
~/Documents/workbuddy-figma-plugin,companion/模板目录已在.gitignore里排除。别把生成物提交上去。整个链路不经过任何第三方服务器,WorkBuddy → 本地 → Figma,三点直连。
项目结构
workbuddy-figma/
├── install.mjs 一键安装:生成 token、配对插件、写 MCP 配置、注册到 Figma
├── server.mjs MCP stdio 服务端,21 个工具
├── selftest.mjs 端到端自检(自带假 Figma 插件,随机端口,不影响日常插件)
├── lib/
│ ├── bridge.mjs HTTP 长轮询桥(双栈监听、连接、队列、超时、状态机)
│ ├── catalog.mjs 18 个画布工具的定义与 JSON Schema
│ ├── assets.mjs 素材读写(base64、SVG 校验、路径穿越防护)
│ └── companion.mjs 配对插件生成(注入 token、端口、插件 id)
└── companion/ Figma 插件资源(未配对模板)
├── manifest.json
├── code.js 跑在 Figma 沙箱里的主线程
└── ui.html 插件 UI,通过 postMessage 与主线程通信运行期产物(不进仓库):
~/.workbuddy/workbuddy-figma/ 配对 token、插件 id 的 salt
~/Documents/workbuddy-figma-plugin/ 实际给 Figma 用的已配对插件(含本机 token)与上游的关系
本项目基于 DSH-to-Figma(MIT,© 2026 Duoasa)。
复用了它的桥接协议、工具定义、素材处理和 Figma 伴生插件资源; 自己重写的是 MCP 服务端层(上游绑定了 DeepSeek Harness 的插件运行时,无法直接用于 WorkBuddy)、一键安装、端到端自检,以及针对 WorkBuddy 的适配。
上游项目的版权声明保留在 LICENSE 里。
License
MIT © 2026 kkse7en 基于 DSH-to-Figma © 2026 Duoasa(MIT)
Available Tools
21 toolscreate_sessionA
Create a local task recording UUID for the selected Figma file. Reuse it across calls, including explicitly selected other files. This does not create a cloud session or switch documents.
Inputs: fileKey (required), description (required), sessionId.
download_assetsC
Export nodes to workspace files as PNG/JPG/SVG/PDF, optionally with original image bytes. Outputs are saved under .figma/assets.
Inputs: scale, format, nodeId, nodeIds, +1 more.
figma_select_documentA
同时连接了多个 Figma 文件时,指定要操作哪一个。connectionId 从 figma_status 获取。
Inputs: connectionId (required).
figma_setupA
生成本机已配对的 Figma 伴生插件,返回需要导入的 manifest.json 路径。首次使用或重装时调用。
Inputs: no named parameters.
figma_statusA
查看当前连接的 Figma 文档、插件版本与桥接状态。第一次使用、或操作失败后先调这个。
Inputs: no named parameters.
get_component_contextC
Read component, component set or instance properties and descendants.
Inputs: depth, nodeId, profile, maxBytes, +1 more.
get_design_contextA
Read a target subtree and CSS for design-to-code work. For a few native properties prefer bounded get_metadata or one scoped script; do not read an entire subtree for a few descendant values. Set includeScreenshot:false unless an image is needed; screenshots are included by default. No cloud code generation.
Inputs: depth, scale, nodeId, profile, +4 more.
get_figjamB
Read FigJam structure. Set includeScreenshot:false for structural checks; screenshots are included by default.
Inputs: depth, scale, nodeId, profile, +4 more.
get_librariesB
Read available team variable libraries through the public Plugin API.
Inputs: no named parameters.
get_local_component_linksA
Read local DSH component-to-code links. These are plugin data, not published Code Connect mappings.
Inputs: nodeId (required).
get_metadataA
Read a bounded layer tree; prefer summary for discovery. Without nodeId, returns pages and current page. Offset/limit page direct children and require nodeId with depth >= 1. Follow truncation continuations. Only reads without profile, budget or paging options reconcile an uncertain write.
Inputs: depth, limit, nodeId, offset, +3 more.
get_motion_contextC
Read prototype reactions and public motion data when exposed. Cloud timeline/code conversion is not emulated.
Inputs: nodeId.
get_screenshotA
Return an actual PNG screenshot as a DSH image attachment. Requires an exportable node.
Inputs: scale, nodeId, quality.
get_selectionC
Read the current page and selected nodes. Prefer summary for discovery.
Inputs: profile, maxBytes, maxNodes.
get_variable_defsA
Read local variables or collection inventory. collectionsOnly:true lists collections including empty ones without reading variables; query then matches collection names. Otherwise collections describe the returned variable page or requested IDs, not a complete collection inventory. Follow coverage and pagination before concluding absence. Summary omits values; no arguments preserves the full result.
Inputs: ids, type, limit, query, +5 more.
import_sceneA
Import a local JSON scene as native editable Figma nodes. Prefer use_figma for complex components, variables, graphs or Slides. See the scene reference.
Inputs: nodes (required), parentId.
list_fontsA
Find available font families and exact styles. No arguments returns the legacy array; filters or pagination return fonts and pagination.
Inputs: limit, query, style, family, +1 more.
search_design_systemB
Search local components, variables and styles. queries batches {entity,query} searches and returns results in order. Legacy query/kind also supported. Components use current page unless pageId supplied. Pagination is per kind; no cloud component-library or Code Connect search.
Inputs: kind, limit, query, offset, +7 more.
set_local_component_linksB
Save local component-to-code links in Figma plugin data. Does not publish Code Connect.
Inputs: links (required), nodeId (required).
upload_assetsB
Import workspace raster/SVG files as editable SVG layers or image fills. Files must be inside the current Work workspace.
Inputs: files (required), parentId.
use_figmaA
Run JavaScript using the figma-use 16 contract in the selected local Figma document. Read figma-workbench first. Top-level await/return, query/QueryResult, matches/set/tree, auto layout, screenshots and io.write are supported. Include description, fileKey and sessionId from create_session. Page context starts at the first page every call; switch at most once. Return affected IDs. Errors include safeToRetryWithoutCanvasRead. Requires companion featureVersion 3.
Inputs: code (required), fileKey, sessionId, skillNames, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
The read surface has several overlapping tools — get_selection, get_metadata, get_design_context, get_screenshot, and get_figjam all inspect document state, and the distinctions rely on dense guidance like 'prefer summary for discovery' or 'bounded tree.' The descriptions do steer an agent, but misselection between get_metadata and get_design_context is plausible. The write/session/assets tools are clearly distinct.
Nearly everything follows snake_case verb_noun (get_selection, list_fonts, download_assets, set_local_component_links), and the local/set_local pair signals read/write predictably. Minor deviations: a figma_ prefix on three tools and noun-first forms like get_figjam and get_screenshot.
At 21 tools the surface is heavy for what is largely one domain (inspect + mutate a Figma doc), and several read tools could plausibly be collapsed. Each tool does have a defensible niche, so it's borderline rather than bloated.
Coverage spans document selection/session setup, deep reads (metadata, design context, components, variables, libraries, motion, FigJam), asset import/export, and arbitrary mutation via use_figma scripting, so no dead ends for typical workflows. Minor gaps: no first-class node create/delete/styling tools independent of scripting, and no published Code Connect operations.
Related MCP Connectors
The Figma MCP server brings Figma design context directly into your AI workflow.
Design canvas for agents: create, edit, render and export Figma-shaped designs over MCP.
Official Fibery MCP server: query and update your workspace from any AI client via OAuth.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceUnofficial local MCP bridge for reading the currently open Figma file through a Figma plugin. Provides tools to inspect selection, file info, and export selected nodes as SVG/PNG.MIT
- FlicenseBqualityCmaintenanceA local bridge that lets MCP clients inspect, export, and modify Figma files through a development Figma plugin.65-
- AlicenseBqualityCmaintenanceLocal MCP server connecting AI clients to the Figma desktop app for inspecting and editing Figma documents via the Plugin API.1616 npm1MIT
- AlicenseNot gradedqualityBmaintenanceLocal-first MCP bridge for live Figma documents, enabling design inspection, editing, asset export, component authoring, and variable management through a plugin and WebSocket server without consuming Figma REST API requests.1MIT