figma-mcp-bridge

Agent 生成设计、目视检查渲染结果、检测布局缺陷，并实时自我修正——整个过程无需人工介入。

问题所在

编码 Agent 在 Figma 中基本上是盲目的。大多数 Figma MCP 服务都是只读的——它们会将设计转换为文本，供模型据此编写代码，然后交互就此结束。能够写入的服务，要么需要付费 Figma 席位并受每月工具调用配额限制，要么只提供固定的命令集合（create_rectangle、set_fill），一旦任务稍微具体一些就无法满足需求。

而且，没有任何一种服务能回答写入之后真正重要的问题：效果看起来对吗？ 一个绘制卡片后收到 {"ok": true} 就继续执行的 Agent，无法发现文本溢出、对比度不合格，或画框覆盖了其他人的作品。

这个桥接服务不仅能闭合这一反馈环路，还加入了自主 Agent 要安全操作真实设计文件所需的防护措施。

有何不同

简而言之： 如果你只想将现有设计转换为代码，Framelink 是最佳选择。如果你已经订阅了付费 Figma 计划并需要 Code Connect，官方服务是最稳妥的选择。如果设计工作由 Agent 负责，那么此桥接服务就是为这种场景打造的——它需要自由写入、检查自己的成果，并在出错时能够撤销操作。

工作原理

flowchart LR
    subgraph AI ["🤖 Coding Agent"]
        LLM["Claude Code · Cursor<br/>Antigravity · Windsurf"]
    end

    subgraph Bridge ["⚡ MCP Server — Node.js, 0 deps"]
        Router["Tool Router<br/>+ Job Ledger<br/>+ Target Router"]
        Opt["Token Optimizer<br/>REST + LIVE"]
    end

    subgraph Figma ["🎨 Figma Desktop"]
        Plugin["Bridge Plugin<br/>Checkpoint Journal<br/>Component Index"]
        Canvas["Live Canvas"]
    end

    LLM -->|"stdio JSON-RPC"| Router
    Router <-->|"WebSocket :8765"| Plugin
    Plugin -->|"execute in sandbox"| Canvas
    Canvas -->|"export PNG"| Plugin
    Plugin -->|"raw node tree"| Opt
    Opt -.->|"86% smaller"| LLM
    Plugin ==>|"screenshot + warnings"| LLM

Agent 通过 stdio 使用纯 MCP 通信。服务通过手写的 RFC 6455 WebSocket 监听 :8765，Figma 插件会连接到这里——因此命令可以直接到达画布，无需承受轮询延迟， 结果（包括数 MB 的 base64 PNG）也会直接流式传回。

快速开始

npx mokido

或者，如果你想先查看安装脚本，再让它接触你的机器——脚本本身相同，只是获取方式 不同：

git clone https://github.com/kolganovr/mokido.git
cd mokido
node install.mjs

两种方式都会安装服务和插件，并在找到的每个 AI 客户端配置中注册 MCP 服务——Claude Desktop、Claude Code、Cursor、Windsurf、Antigravity。npm 包的存在纯粹是为了让第一条命令更短；它不会增加任何运行时依赖——它的 package.json 中 dependencies 也为空，也不需要 Python。node 是此项目唯一需要的运行时，安装程序和服务都如此。

然后，在 Figma Desktop 中：

1. Plugins → Development → Import plugin from manifest… → 选择 figma-plugin/manifest.json
2. 按 Ctrl + Alt + P（macOS：Cmd + Option + P）启动 Mokido
3. 状态变为绿色——CONNECTED

重启 AI 客户端，让它加载新工具。随时可以用以下命令验证：

npx mokido --doctor   # or: node install.mjs --doctor

npx mokido --token "your_figma_personal_access_token"
# or: node install.mjs --token "your_figma_personal_access_token"

它能为 Agent 做什么

1. 自由编写，然后查看结果

capture: true 会返回一张 PNG，显示本次调用刚创建或修改的内容——自动将视图框定到 已更改的节点，而不是整个页面，也绝不会劫持用户的选区。

// agent calls figma_execute_code
{ "code": "const f = figma.createFrame(); /* ... */ return f.id;", "capture": true }

// agent gets back — text + image in one response
{
  "ok": true,
  "created":  ["12:34"],
  "warnings": ["Text \"Total\" has ~3.1:1 contrast against its parent fill (WCAG AA wants 4.5:1)."],
  "checkpoint_id": "cp_mfk3p2a_7",
  "duration_ms": 840
}

warnings 数组会对已触及的子树进行快速自动检查——文本溢出、对比度过低、节点尺寸为零。它能无需额外往返获取截图，就捕捉到明显错误。

2. 撤销 Agent 执行的任何操作

每次写入都会自动创建检查点。一次调用即可撤销——不会用 Ctrl+Z 撤销到人类自己所做的无关修改。

// agent calls figma_rollback
{ "checkpoint_id": "last" }

// gets back
{
  "ok": true,
  "checkpoint_id": "cp_mfk3p2a_7",
  "label": "Generate checkout flow",
  "removed":  ["12:34", "12:35"],   // nodes the call created — deleted
  "restored": ["9:11"],             // nodes it modified — properties put back
  "missing":  []                    // ids that no longer exist
}

创建的节点会通过 figma.create*() 外层的 Proxy 自动跟踪。属性编辑会在快照时跟踪。删除操作会如实报告为不可恢复，而不是悄悄丢失。

3. 读取实时画布只需约 700 个 token，而非约 5,000 个

云端工具所用的精简 + Pseudo-JSX 流水线也可用于读取当前打开的内容。在一个符合实际情况的 6 卡片布局上测得：20 KB 原始 API JSON → 2.7 KB（缩小 86%）。

<Frame id="1:1" name="Landing" w="1440" h="900" row gap="20">
  <Frame id="2:0" name="Card" w="300" h="200" col gap="12" pad="20" bg="#FFFFFF" radius="16">
    <Icon id="3:0" name="ic_check" size="24" strokeWidth="2" />
    <Text id="4:0" color="#1A1A1F" font="Inter 18px">Feature 0</Text>
  </Frame>
</Frame>

budget_tokens 会限制响应大小：如果请求的深度超出限制，服务会将已获取的树重新序列化为更浅的结构——无需第二次往返——并附加注释，说明执行了什么操作，以及要获取更多内容时应使用的 id。

4. 为沙盒添加重启后仍能保留的新本领

每次 figma_execute_code 调用都会创建一个全新的函数作用域，因此辅助函数通常会立即消失。 bridge.define 会在 .fig 文档内部编译并存储模块：

// once
bridge.define("kit", `
  async function label(parent, text) { /* ... */ }
  module.exports = { label };
`);

// in any later call — including next week, after a Figma restart
const { label } = bridge.require("kit");

5. 超时后仍可继续运行的长任务

如果生成任务在 45s 后仍在运行，系统会返回 job_id，而不是报错；插件会继续工作。随后，figma_job_status 会阻塞，直到任务完成（最长等待 wait_ms，默认 45s）——一次调用即可，无需轮询循环。任务运行期间会附带 progress(step, of, note) 提供的进度；静默 2 分钟的任务会标记为 stalled，插件断开连接的任务则会立即以 PLUGIN_DISCONNECTED 失败，而不是一直等到超时。如果调用在仍有任务运行时超时，系统会说明这一情况（PLUGIN_BUSY，并注明任务），而不是让你盲目重试。

6. 为 Token 账单而打造

在 Agent 循环中，一次工具调用要付两次成本：一次是在它返回时，另一次是在之后的每一轮，因为它的输出会保留在每轮都要重新读取的上下文中。因此，这个桥接工具优先考虑减少轮数和缩小残留内容：

每个默认值都可按调用覆盖，也可通过环境变量按安装覆盖：FIGMA_MCP_SCALE、 FIGMA_MCP_MAX_PX、FIGMA_MCP_MAX_IMAGES、FIGMA_MCP_MAX_OUTPUT_BYTES、FIGMA_MCP_MAX_OUTPUT_CEILING（0 = 无上限）、FIGMA_MCP_JOB_WAIT_MS、 FIGMA_MCP_ESCALATE_MS、FIGMA_MCP_RECONNECT_GRACE_MS。

更新内容

4.2.7：compare / like 的差异结果以一行 REF 结尾，其中包含精确的参考值，让 Agent 无需额外读取 props 就能修复副本；find 会返回找到内容的子树；view: "flow" 无需 node_ids 即可使用；bridge.setText 会保留混合字体。在内部基准测试中（Gemini Flash，使用种子任务），每个系列的模型轮数从 112 降至 83，写入后的验证轮数从 11 降至 1。更新后请重新加载 Figma 插件。 历史记录：CHANGELOG.md。

工具参考

工具分为多个层级提供，因此每轮发送给模型的架构列表大小会与实际可用工具的数量相称：

没有 REST Token 时，Agent 看到的是 13 个工具，而不是 23 个，也不会浪费调用去尝试只会返回 REST_TOKEN_MISSING 的工具。

工程说明

那些看起来简单、实际却更难的部分，以及代码为何采用这种设计。

测试

七个无需依赖的测试套件，均可直接使用 node 运行：

node tests/bridge-runtime.test.js   # sandbox runtime, module persistence, checkpoint/rollback
node tests/layout-packer.test.js    # row/grid packing, collision grid
node tests/optimizer.test.js        # jsx/tree/json serialization, budget truncation
node tests/mcp-protocol.test.js     # real server over stdio: initialize, tools/list, tiering
node tests/install.test.js          # config merge/reuse, token persistence, stale-file cleanup
node tests/token-economy.test.js    # fake plugin over a real WebSocket: budgets, long-poll, proxy
node tests/output-shrink.test.js    # line-wise shrinking, offset paging, output ceiling, syntax pre-check

mcp-protocol.test.js 会将实际服务作为子进程启动，并通过 NDJSON 与之通信——这与真正的 MCP 客户端使用的传输方式相同，而不是导入内部实现。

仓库结构

mokido/
├── figma/                    # MCP server (Node.js, stdio + WebSocket)
│   ├── index.js              # protocol, tool router, job ledger, target router
│   ├── optimizer/            # AST pruner, style collapser, JSX/tree serializers
├── figma-plugin/             # Figma Desktop plugin
│   ├── code.js               # sandbox executor, bridge runtime, checkpoints, capture
│   └── ui.html               # HUD — stream, settings, control (pause / undo)
├── docs/GUIDE.md             # long-form agent guide (server instructions are inline in index.js)
├── tests/                    # 7 suites, 0 dependencies
├── install.mjs               # cross-platform installer, updater, doctor (Node only)
└── AGENTS.md                 # onboarding protocol for AI agents

来源

1. 官方服务的席位和配额要求 — Figma：Figma MCP 服务指南，Figma 开发者文档：速率限制与访问
2. 在一个模拟真实 REST 输出的 6 卡片布局测试样例上测得的令牌减少量：20,587 B 原始数据 → 2,862 B Pseudo-JSX（86.1%）/ 1,912 B 树结构（90.7%）。该测试样例已纳入代码库并有断言 — 运行 node tests/optimizer.test.js 即可复现准确数据。

对比反映了截至 2026 年 8 月公开记录的行为。替代方案仍在积极开发中 — 请先核实当前功能，再仅依据此表做出决定。

许可证

MIT · 由 Roman Kolganov 构建