figma-vault

figma-vault

英語 · ロシア語

Figma のフレームを一度取得すれば、Claude Code、Codex、または任意の MCP エージェントが、オフラインで、Figma トークンもレート制限もなしに何度でも読み取れます。

• Figma へのリクエストは一度にまとめて実行し、エージェントが何度読み取っても、その後のリクエストはゼロです。 同じファイル内の画面では、構造の読み取りと画像のレンダリングをまとめて実行できます。
• アイコンのコストはゼロです。 実際の画面ではアイコンが141個ありましたが、追加のリクエストは発生しませんでした。
• Vault をコミットすれば、チームに Figma へのアクセス権は不要です。 ライセンスもトークンも必要ありません。

30秒で試せます。Figma トークンは不要です。

npm i -g figma-vault
figma-vault init && figma-vault demo && figma-vault check

仕組み：pull でフレームを正規化し、ディスクに書き込みます。その後、エージェントが MCP 経由で読み取ります。

one developer:      figma-vault add <link>  →  vault  →  git commit
the rest of the team:  the agent reads it over MCP, no Figma token needed

問題

Figma の MCP サーバーと REST API にはレート制限があり、プランによっては上限が非常に低く設定されています。UI の構築中、エージェントは余白、色、フォントサイズを確認するために、頻繁にデザインを参照します。1回のセッションで数十回の呼び出しが発生することもあります。すぐに上限に達し、作業が止まってしまいます。

figma-vault では、Figma への呼び出し回数はエージェントの動作に左右されません。各デザインで必要な呼び出し回数は固定されており、pull 時に一度だけ実行されます。

	Figma Dev Mode MCP	figma-vault
Figma を呼び出すのは誰か	作業中のエージェント	CLI が一度だけ
呼び出し回数	エージェントの作業に応じて増加	デザインごとに固定
読み取る人全員にトークンが必要か	はい	いいえ
オフラインで動作するか	いいえ	はい

副次的な効果として、デザインがリポジトリ内のファイルになります。Figma ファイルへのアクセス権がない開発者（ライセンス、権限、トークンがない場合）も、デザイン全体を利用できます。

比較

同じ問題に取り組む他のプロジェクトもあります。Framelink Exporter プラグインはオフラインで使えるようデザインを zip にエクスポートし、Framelink の Figma MCP にはキャッシュ機能を追加したフォークがあります。figma-vault は異なるアプローチを取ります。

• Vault はコミットすることを前提としています。 1人がデザインを pull すれば、チーム全員が git から読み取れます。他のメンバーが Figma にアクセスする必要はありません。
• アイコンのリクエストはゼロです。 ベクターパスはノードツリーとともに取得され、SVG はローカルで生成されます。Figma 経由でレンダリングすると、画像レンダリングの上限を消費します。
• 形式は固定され、検証されます。 doc.json は明文化された契約に従い、厳格なバリデーターがすべてのファイルをチェックします。

インストール

Node.js 22 以降が必要です。

npm i -g figma-vault

方法1. プロジェクト単位

figma-vault init

これにより .figma-vault/ が作成され、サーバーがプロジェクトの .mcp.json に登録されます（既存の他のエントリーはそのまま保持されます）。.env が .gitignore に追加され、Claude Code 用の /figma スラッシュコマンドがインストールされます。

--no-command を指定すると /figma コマンドを省略し、エージェントには読み取り専用の vault_* ツールのみが提供されます。

方法2. リポジトリに何も追加しない

figma-vault init --global

Vault は ~/.figma-vault/ に置かれ、サーバーはエージェントのユーザー設定に登録されます。プロジェクトのリポジトリには、このツールの存在が知らされることはありません。プロジェクトに設定や依存関係を追加できない場合に使用してください。

使用方法

figma-vault add "https://figma.com/design/KEY/Project?node-id=127-4532"
# Export several selections together; links from the same file share requests:
figma-vault add "<frame link 1>" "<frame link 2>"
# Keep the node trees if image rendering is unavailable:
figma-vault add "<frame link 1>" "<frame link 2>" --no-assets
# A SECTION/CANVAS link can expand into its frames (up to 20 by default):
figma-vault add "<section link>" --expand --max-screens 20

リンクを取得するには、Figma でフレームを右クリックし、Copy link to selection を選択します。

figma-vault limits "<frame link 1>" "<frame link 2>" # probe access before pulling
figma-vault list              # what has been pulled so far
figma-vault check             # verify the whole chain works
figma-vault demo              # add a demo design, no token needed

CLI の出力、エラー、MCP ツールの説明は、デフォルトで英語です。インストールされる /figma コマンドも英語です。README.ru.md はドキュメントのみを翻訳したものです。

init の後、Claude Code では次のコマンドを使用できます。

/figma <frame link> [more frame links...]

デザインを取得して MCP 経由で読み込み、プロジェクトの規約に沿って UI を構築します。

Figma のリクエスト数に対する取得処理のコスト

REST API の制限は、トークン、プラン、シートの種類によって異なります。ノードの読み取りと画像のレンダリングは、どちらも Tier 1 エンドポイントです。figma-vault limits "<link>" [more links...] は、浅いノード読み取りを 1 回に加えて、ファイルごとに最大 ceil(S/40) 回の画面レンダリングリクエストを消費します。SECTION と CANVAS の選択範囲は画像全体としてのレンダリングをスキップし、子画面の確認も行いません。プローブが成功しても、取得全体の成功が保証されるわけではありません。アセットのレンダリングで追加のリクエストが必要になる場合があります。

選択された画面が S 個、一意のラスターアセットが R 個あるファイルで、各画面のラスターアセットが 40 個未満の場合、取得が成功すると通常、次のリクエスト数になります。

	リクエスト数
選択されたノードツリー（/v1/files/:key/nodes）	ファイルごとに 1 回
スクリーンショットとラスターアセット（/v1/images、40 ID 単位のバッチ）	ファイルごとに ceil((S + R) / 40) 回
ローカルジオメトリを持つアイコン	0

たとえば、1 つのファイルに 2 つの画面と 3 つの一意のラスターアセットがある場合、5 つの ID を 1 つのバッチにまとめられれば、ノード読み取り 1 回と画像レンダリング 1 回で済みます。1 つの画面にラスターアセットが 40 個以上ある場合、スクリーンショットは個別にレンダリングされます。--expand はまず depth=1 でコンテナーをプローブするため、ファイルごとに少なくとも 1 回のノードリクエストが追加されます。SVG フォールバックのレンダリング、失敗したリクエスト、再試行により、呼び出しが増える場合があります。実際の 332 ノードのデザインでは、141 個のアイコンにレンダリング呼び出しは不要でした。取得後、エージェントが Figma を再度呼び出すことはありません。

デザインと照合して結果を確認する

figma-vault verify は、エージェントが構築したページとデザインを比較します。このパッケージにはブラウザーは含まれていません。スナップショットは、プロジェクトがすでに使用しているもの（Playwright、DevTools、エージェントのブラウザーツール）で取得します。

1. ページのルート要素に data-figma-node-id="<root node id>" を設定し、主要なブロックにもそれぞれのノード ID を設定します。
2. figma-vault verify <docId> --snippet を実行すると、スクリプトが出力されます。ページ上で実行し、返された内容をファイルに保存します。
3. figma-vault verify <docId> --snapshot <file> で確認します。
   • テキスト： デザイン内の表示されているテキストがすべてページ上にあること。
   • ジオメトリ： マークされた各ブロックの位置とサイズが、デザインと一致していること。デフォルトでは許容誤差は 2 px です（--tolerance）。

結果は PASS（終了コード 0）、FAIL（1。不一致の一覧を表示）、または INCOMPLETE（2。マークされた要素がなく、ジオメトリを確認できない場合）です。プロジェクトにブラウザーがある場合、/figma コマンドはこの手順を自動で実行します。

Figma トークンなしで試す

新しいデザインを取得する場合にのみ、トークンが必要です。読み取りはトークンなしで機能します。取得を行う人以外には、これが通常の設定です。そのため、トークンを作成せずにインストール全体をテストできます。

figma-vault init && figma-vault demo && figma-vault check

check は実際の MCP サーバーを子プロセスとして起動し、プロトコル経由で通信します。実際に問題がある場合はコード 1 で終了するため、CI で使用できます。

トークン

Figma で、Settings → Security → Personal access tokens → Generate new token の順に選択します。トークンに必要なスコープは 1 つだけです。File content → Read-only。

CLI を実行するディレクトリにある .env ファイルに、FIGMA_TOKEN=figd_... という行を追加するか、環境変数として設定します。両方が設定されている場合は、環境変数が優先されます。

エージェントが取得する内容

MCP サーバーは、読み取り専用のツールを6つ公開します。

ツール	返す内容
vault_list	Vault 内のデザイン
vault_get_doc	デザインのノードツリー。maxDepth で深さを制限します
vault_get_node	1つのノードのサブツリー
vault_search	名前またはテキストで見つかったノード
vault_get_tokens	色、タイポグラフィ、エフェクト
vault_get_asset	画像またはアイコン

ツリーは正規化されています。

• オートレイアウトは、gap と padding を含む mode: row|column になります。
• 座標は親を基準にしています。
• スタイル、グラデーション、テキストは、1つのテキスト内の色の異なる断片（text.runs）も含め、予測しやすい形でまとめられます。
• Figmaで非表示になっているノードも、hidden: true として保持されます。デフォルトではエージェントには渡されませんが、親ノードには省略された数が示されます（hiddenOmitted）。この画面では無効になっている任意のスロットを持つ再利用可能なコンポーネントを作成する場合は、includeHidden: true を指定してください。

デバッグ用に、Figmaの生のレスポンスは隣にある raw.json に保存されます。

実際のデザインでは、正規化によってツリーのサイズが約7分の1になります。

raw.json   1.9 MB   raw Figma response
doc.json   256 KB   what the agent reads

これはディスク容量以上のものを節約します。2 MBではなく256 KBを読み込むエージェントは、UIを大幅に正確に再構築できます。

Vault の構成

<vault>/
  index.json                 list of designs
  <docId>/
    doc.json                 normalized tree, the main artifact
    raw.json                 raw Figma response
    screenshot.png           render of the whole frame
    assets/                  icons and images

figma-vault/doc@1 スキーマについては、docs/CONTRACT.md（ロシア語）で説明しています。厳密なバリデーターで検証します。0.1.0（doc@0）で取得したVaultも、引き続きそのまま読み込めるため、再取得する必要はありません。

doc.json だけで完結します。MCP サーバーが raw.json を読み込むことも、ネットワークにアクセスすることもありません。

既知の制限事項

これはMVPです。現時点でできないことは次のとおりです。

• レート制限。 ノードの読み込みと画像のレンダリングは、どちらもTier 1です。どちらのエンドポイントも429を返すことがあり、制限が数日続く場合もあります。アイコンはレンダリングに依存しなくなりましたが、フレームのスクリーンショットとラスター画像は引き続き依存します。クライアントは Retry-After に従って最大3回まで再試行し、待機時間は1分を超えません。Figmaから数日間待つよう指示された場合は、プル時にノードツリーを保持し、理由を警告として記録して、処理を失敗させません。プルする前に figma-vault limits を実行してください。
• テキスト内の断片について保持されるのは、色とウェイトだけです。 テキストの一部に適用されたグラデーション、異なるフォント、下線は失われます。
• コンポーネントのバリアントが多いデザインでは、大きな doc.json が生成されます。 現在は非表示のスロットも保持します。332ノードの画面では、これによって非表示のノードが3,400個追加され、ファイルサイズは444 KBから5 MBに増えました。デフォルトでエージェントに渡されるのは約100 KBですが、ファイルはGitに含まれます。

テスト方法

リポジトリ内のフィクスチャは合成データです。29ノードを含み、Figmaトークンなしでツールをインストールし、一連の処理が動くことを確認できます。

精度は別途、ここでは内容を公開していない2つの実際のデザインで確認しました。深さ15階層、332ノードの製品画面での結果：

確認項目	結果
再構築されたマークアップ内にあるデザインテキスト	41件中41件
アイコン	15個中15個、リンク切れ0件
必要なプレースホルダー	1個（ラスター形式のアバター）
以前の計測時のプルにおけるFigmaへのリクエスト	3件（レンダリング統合前）
コントラクトに対する doc.json の検証	合格

未確認事項： ピクセル単位での完全な一致。npm run dev → /compare/<name> を使い、Figmaの参照レンダリングと目視で比較します。figma-vault verify はテキストと、マークされたブロックのジオメトリを確認しますが、色、フォント、ピクセルは確認しません。

意図的に対応していないこと

SaaSでも、Figmaの代替でも、リアルタイム同期ツールでもありません。認証、課金、チーム、ユーザー、サーバーサイド機能はありません。MCP サーバーは開発者のマシン上でエージェントの子プロセスとして動作し、stdio経由で通信します。デプロイは不要です。

そのほかのドキュメント（ロシア語）

• docs/INTEGRATION.md：チームへの導入、痕跡を残さないモード、Figmaトークンを使わない確認方法。
• docs/ADAPT.md：ツールをプロジェクトのデザインシステムに適合させる方法。

開発

npm install
npm test          # 85 tests
npm run typecheck
npm run dev       # local preview of rebuilt markup and comparison with the design

2 つの AI エージェントが、AGENTS.md のプロトコルに従って、このプロジェクトを並行して開発します。コード領域を分担し、タスクボードと共有ログを使用します。 各コミットには作成者のタグが付けられます。

ライセンス

MIT