figma-mcp-bridge

エージェントがデザインを生成し、レンダリング結果を目視で監査してレイアウトの欠陥を検出し、リアルタイムで自動修正します。人間が介在する必要はありません。

問題点

コーディングエージェントは、Figma 内では事実上、何も見えません。ほとんどの Figma MCP サーバーは読み取り専用です。デザインをテキストに変換してモデルがコードにできるようにしますが、そこで処理は終わります。書き込み可能なものは、有料の Figma ライセンスと月間のツール呼び出し上限が必要なものか、作業が具体的になるとすぐに対応できなくなる固定コマンド群（create_rectangle、set_fill など）を公開しているもののどちらかです。

そして、書き込み後に本当に重要な問いに答えられるものはありません。**見た目は正しかったのでしょうか？**図形を描いて {"ok": true} を受け取り、そのまま先へ進むエージェントには、テキストがはみ出したり、コントラストが不十分だったり、フレームが他の人の作業に重なったりしても、気づく手段がありません。

このブリッジはそのループを完結させ、自律型エージェントに実際のデザインファイルを任せるために必要な安全策も備えています。

他との違い

**要点：**既存のデザインをコードに変換したいだけなら、Framelink が最適です。有料の Figma プランをすでに利用していて Code Connect が必要なら、公式サーバーが最も安全な選択肢です。このブリッジは、エージェント自身がデザインを行う場合に適しています。自由に書き込み、自分の作業を確認し、間違えたときには元に戻せる必要があるケース向けです。

仕組み

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

エージェントは、標準入出力経由でプレーンな MCP を使用します。サーバーはポート :8765 で手書きの RFC 6455 WebSocket を管理し、Figma プラグインが接続します。そのため、ポーリングによる遅延なしでコマンドがキャンバスに届き、結果（数メガバイトの 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"

エージェントにできること

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. エージェントが行った操作を元に戻す

書き込みのたびにチェックポイントが自動的に作成されます。1回の呼び出しで元に戻せるため、人間が行った無関係な作業まで 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トークンで読み取る（約5,000トークンの代わりに）

クラウドツールで使用しているものと同じ、枝刈りと Pseudo-JSX のパイプラインを、現在開いているキャンバスに適用します。実際の6カードのレイアウトで測定した結果、**API 生 JSON 20 KB → 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 はレスポンスの上限を設定します。要求された深さが上限を超えた場合、サーバーは取得済みのツリーをより浅い深さで再シリアライズします。2回目の往復は不要です。さらに、実行内容と、追加情報を取得するために指定すべき 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. タイムアウトしても終了しない長時間ジョブ

生成処理が45秒を過ぎても実行中の場合、失敗として扱う代わりに job_id が返され、プラグインは処理を続行します。続いて figma_job_status を呼び出すと、ジョブが完了するまでブロックします（デフォルトでは45秒、wait_ms まで）。ポーリングループではなく、1回の呼び出しで済みます。実行中は progress(step, of, note) による進捗が含まれます。2分間進捗のないジョブは stalled としてフラグが立ち、プラグインが切断されたジョブは時間切れを待たず、直ちに PLUGIN_DISCONNECTED で失敗します。実行中のジョブがあるために呼び出しがタイムアウトした場合は、理由を示す（ジョブ名を含む）PLUGIN_BUSY が返され、状況が分からないまま再試行することを促しません。

6. トークンコストを抑える設計

エージェントのループでは、ツール呼び出しのコストは二重に発生します。結果が返ってきたときに一度、さらにその後の各ターンで、出力が毎回読み直されるコンテキストに残るためです。そのため、このブリッジはターン数の削減と残存データの縮小を優先しています。

各デフォルト値は呼び出しごとに上書きでき、環境変数を使ってインストールごとに設定することもできます：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行で終わるため、エージェントは追加のprops読み取りなしでコピーを修正できます。findは見つかったもののサブツリーを返します。view: "flow"はnode_idsなしで動作します。bridge.setTextは混在フォントを保持します。内部ベンチマーク（Gemini Flash、シード付きタスク）では、シリーズごとのモデルのターン数が112から83に、書き込み後の検証ターン数が11から1になりました。更新後はFigmaプラグインを再読み込みしてください。 履歴：CHANGELOG.md。

ツールリファレンス

ツールはティアに分けて提供されるため、各ターンでモデルに送信されるスキーマ一覧は、実際に使用可能なツールに応じた規模に保たれます。

RESTトークンがなければ、エージェントに表示されるツールは23個ではなく13個です。そのため、REST_TOKEN_MISSINGだけを返すツールへの呼び出しで時間を無駄にすることもありません。

エンジニアリング上の注意点

見た目以上に難しかった部分と、その理由からコードがこのような形になっていることを説明します。

テスト

依存関係のない 7 つのテストスイートは、素の 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 は実際のサーバーを子プロセスとして起動し、実際の MCP クライアントが使うものと同じトランスポートである NDJSON を使って通信します。内部実装をインポートする方式ではありません。

リポジトリの構成

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 Developer Docs：レート制限とアクセス
2. 実際の REST 出力を模した 6 カードのレイアウトフィクスチャで測定したトークン削減量：生データ 20,587 B → Pseudo-JSX 2,862 B（86.1%）／ツリー 1,912 B（90.7%）。フィクスチャはリポジトリにチェックインされ、アサーションも設定されています。正確な数値を再現するには、node tests/optimizer.test.js を実行してください。

この比較は、2026年8月時点で公開されている情報に基づいています。代替ツールも活発に開発されています。この表だけを参考に判断するのではなく、最新の機能を確認してください。

ライセンス

MIT · Roman Kolganov によって開発