figma-to-code-mcp

このプロジェクトの目的

Figma To Code MCP は、UI の構築に LLM が必要とする情報だけを抽出し、コード生成に関係のない Figma 固有のメタデータを取り除くことに特化しています。その結果、次のようなメリットがあります。

• ✅ 実際の Figma ファイルで サイズを 99.5% 削減（65 MB → 128 KB）
• ✅ コンパクトで CSS に対応付けやすいフィールド（style.background、layout.direction、style.fontSize）
• ✅ UI 構築に必要なデータ一式を保持（レイアウト、スタイル、テキスト、コンポーネント）
• ✅ ノードごとのレイアウトとスタイルに加え、再利用可能な値を共有トークンレジストリに保存
• ✅ Figma の内部情報を省略 — バウンディングボックスや制約のメタデータは含みません
• ✅ 変数の解決 — Figma の変数を実際の値に解決
• ✅ SVG に対応 — ベクターグラフィックスをディスクにエクスポート
• ✅ パターンの統合 — 繰り返される UI パターンの重複を排除

---

この Model Context Protocol サーバーを使って、Cursor やその他の AI 搭載コーディングツールから Figma ファイルにアクセスできます。

利用可能なツール

ツール	説明
get_figma_design	CSS に準拠した、LLM に最適化されたデザインデータを取得します。SVG アセットと PNG レンダリングをエクスポートします。
get_image_fills	Figma ファイルから画像の塗りつぶし URL を取得します
render_node_images	Figma ノードを PNG 画像としてレンダリングします

get_figma_design は SVG アセットを自動的にエクスポートします。レスポンスには svgAssetsFolder と相対パスの svgPathInAssetFolder ファイル名が含まれます。それらを組み合わせると各ファイルの場所を特定できます。svgOutputDir を使うと、指定したアセットディレクトリに直接エクスポートできます。また、指定されたノードを 1x の PNG としてレンダリングします。レスポンスには renderedDesignNodeAssetsFolder とファイル名 renderedDesignNodePathInAssetFolder が含まれ、これを使ってビルドした結果とデザインを比較できます。個別に登録された read_vector_svg ツールはありません。

デフォルトでは、get_figma_design はデザインで使用されているコンポーネントを componentSets で返します。各コンポーネントには propKeys と propValues（セット内の各メンバーが各プロパティで取り得る値）が含まれます。各セットは専用の JSON ファイルとして componentSetsFolder に書き込まれ、componentSets には各セットの file、propKeys、propValues が一覧表示されます。228 KB を超えるセットは、セット名のフォルダーになります。その file は <set>/index.json となり、バリアントの一覧が記載されます。また、各バリアントは隣接する独自の <nodeId>.json ファイルに保存され、例のように : は - に置き換えられます（例：7-770.json）。COMPONENT_SET ルートも同様に処理されます。バリアントが 228 KB を超えると、その children は別の場所に移され、root.file は <name>/index.json を指し、各バリアントは隣接する <variant name>.json ファイルに保存されます。ルートのバリアントにはノード ID がないためです。すべての file 値は componentSetsFolder からの相対パスです。そのため、バリアントのファイルはセットフォルダーからの相対パスではなく、<set>/<nodeId>.json になります。コンポーネントライブラリからコンポーネントを構築する場合は、includeComponentVariants: true を指定すると、それらのコンポーネントのほかのすべてのバリアント（すべてのサイズ、色、状態）と、そのプロパティ、および取得可能なビジュアルも取得できます。Figma から取得するデータ量が増え、レスポンスも大きくなります。

--skip-image-downloads を指定すると、登録されるのは get_figma_design のみです。SVG のエクスポートは引き続き利用できますが、ノードの PNG はレンダリングされません。

必要なスコープ

次のスコープを含む Figma パーソナルアクセストークンを作成してください。

スコープ	用途
file_content:read	ファイルノード、レイアウト、スタイルを読み取ります
library_content:read	公開済みのコンポーネント／スタイルを読み取ります
library_assets:read	参照されているコンポーネントを公開済みのライブラリソースに解決します
file_variables:read	変数を読み取ります（Enterprise のみ、任意）
file_comments:read	ノードに添付されたコメントを読み取ります（任意）

注： 変数の解決には Enterprise プランが必要です。Enterprise でない場合は、resolveVariables: false を設定してください。

コメントへのアクセスができない場合、コメントなしで抽出が続行され、警告がログに記録されます。

仕組み

1. IDE のチャットを開きます（例：Cursor のエージェントモード）。
2. Figma ファイル、フレーム、またはグループへのリンクを貼り付けます。
3. Cursor にデザインの実装を依頼します。
4. Cursor は CSS に準拠し、LLM 向けに最適化された デザインデータを取得し、正確なコードを生成します。

デザインからページを構築するエージェントは、LLM 向けの指示に従ってください。

この MCP サーバーは、Figma API のデータを LLM に適した形式に変換します。

• 詳細な Figma 内部情報の代わりに、コンパクトなレイアウト／スタイルのフィールド（layout.direction、style.background、style.fontSize）を使用
• それぞれの異なるデザイン値を tokens レジストリから参照するノード単位のスタイル
• 自動レイアウトにはFlexbox のプリミティブを使用し、オーバーレイや自由形式のグラフィックには親要素基準の配置を使用
• 完全な UI データ（色、タイポグラフィ、間隔、効果）
• UI に不可欠な情報をすべて保持しながら、サイズを 99.5% 削減

現在のレスポンスではスキーマ v3 を使用しています。V3_CSS_PROPERTY_MAPPING.md では、現在のレスポンス仕様ではなく、以前の v2 マッピングについて説明しています。

v3 のビジュアル詳細の解釈

レスポンスには、単一のテキストスタイルや単純なフレックスレイアウトでは表現できない詳細を示す省略可能なフィールドが含まれます。

Field	Meaning
textRuns	スタイルのスカラー値による上書きを含む、順序付けられたテキスト範囲です。文字のスタイルが異なる場合にのみ出力されます
layout.position	relative は包含ブロック、absolute は通常フローに属さない子要素を示します
layout.left, layout.top	直近の親の座標系におけるピクセル単位のオフセットです。ゼロおよび負のオフセットも含みます
style.borderWidths	非対称なボーダーの上／右／下／左の明示的な幅です。幅がゼロの辺も含みます
gradientHandlePositions	グラデーションの方向と形状を維持する、ノードローカル座標系における正規化された3つのハンドルです
svgViewport	エクスポートされたSVGのviewBoxをノードローカルのピクセル単位で示します。ノードの元のキャンバス外の描画内容も含みます。x または y は0の場合に省略され、省略されている場合は0を意味します
renderedDesignNodePathInAssetFolder	ビルド結果をデザインと比較するための、renderedDesignNodeAssetsFolder 内にある、指定したノードの1x PNGのファイル名です

既存の完全な text フィールドとノードレベルのスタイルも引き続き含まれます。textRuns がある場合は、text を重複して描画せず、各runを順番に描画してください。まずノードの基本タイポグラフィトークンを解決し、その後、各runのスカラー値による上書きを適用します。各runのテキストを連結すると元の全文になります。プレーンなrunは基本スタイルを継承します。明示的な normal、none、およびゼロの値は、継承したスタイルをリセットします。

位置指定された子要素では、出力された包含ブロック、ローカル寸法、オフセットを維持してください。実際のオートレイアウトの兄弟要素はフレックスフローに配置し、通知のオーバーレイ、チャートの曲線、ガイドは同じ絶対座標空間を共有できます。Figmaのレイアウトモード NONE は、フレックスカラムに変換しないでください。

非対称な線では、borderWidths が均一な borderWidth に置き換わります。共有の border 色は、指定された辺にのみ適用してください。周囲を囲むボーダーを追加しないでください。均一なボーダーには引き続き borderWidth を使用します。

グラデーションのハンドルが単位正方形の外側にある場合があります。ハンドルをクランプしたり、デフォルトの方向に置き換えたりしないでください。

SVGのエクスポートでは、元のノードローカル座標を維持し、ローカルキャンバスと可視形状の和集合を含めます。エクスポートされた各ノードの svgViewport は、ファイルのviewBoxと一致します。ノードの元のレイアウト範囲をラッパーとして維持し、そのうえで svgViewport.x ／ y（省略されている場合は0）に、ビューポートの width ／ height でSVGまたは画像を配置してください。拡張されたアセットを元のノード寸法に合わせて引き伸ばさないでください。チャートの系列ごとに描画範囲が異なる場合がありますが、同じローカル座標系を共有する必要があります。祖先によるクリッピングを維持してください。単色の塗りつぶし色はデザインからエクスポートされたアセットに焼き込まれるため、外部画像でも色が保持されます。

LLM 向け

get_figma_design で取得したFigmaノードからページまたはコンポーネントを作成する場合は、このセクションに従ってください。

レスポンスの概要

フィールド	意味
root	要求されたノードのデザインツリーです。通常のフレームはインラインです。大きなバリアントを持つコンポーネントセットのルートは分割されます（コンポーネントファイルの解決を参照）。
tokens	共有値です。スタイルフィールドには、このレジストリ内のキーが格納されます。たとえば、colors.sys.color.primary.default = #99121C です。
componentSets	デザインで使用されている各コンポーネントセットへの参照です。file、propKeys、propValuesが含まれます。
componentSetsFolder	コンポーネントセットのJSONファイルが格納されているフォルダーです。
svgAssetsFolder	エクスポートされたSVGが格納されているフォルダーです。各ベクターのsvgPathInAssetFolderは、そのフォルダー内のファイル名です。
renderedDesignNodeAssetsFolder、renderedDesignNodePathInAssetFolder	参照画像です（以下を参照）。

レスポンスは大きくなります。テストではページ全体が200～360 KBだったため、rootは一度にすべて読み込まず、部分ごとに読み取ってください。

参照画像

renderedDesignNodePathInAssetFolderは、要求されたノードの1x PNGです。Figmaでレンダリングしたデザインを示しており、構築時にも確認時にも参照します。

• コードを書く前にPNGを開いてください。コンポーネントセットの場合はすべてのバリアントがグリッドに表示され、フレームの場合はフレームが表示されます。
• これを使ってページをセクションに分け、各セクションをroot.childrenの該当部分と照合してください。
• 同じ幅で実装をレンダリングし、PNGとセクションごとに比較してください。差異がなくなるか、説明できるようになるまで修正を続けてください。
• フレームの場合、PNGのピクセル幅はフレームのレイアウト幅と同じです（たとえば、幅410 pxのフレームなら410 pxです）。
• サーバーを--skip-image-downloads付きで実行した場合、Figmaから画像が返されなかった場合、またはダウンロードに失敗した場合、PNGはありません。PNGがない場合は推測せず、ビジュアルチェックをスキップしたことを伝えてください。

プロセス：デザインからページへ

1. ブレークポイントごとにノードを1つ取得します。 Startseite (XS) のような名前のフレームは1つのブレークポイントです。必要なブレークポイントをそれぞれ個別に取得してください。
2. デザインごとに新しいエクスポートフォルダーを使用します。 svgOutputDir を指定してください。このフォルダーには SVG、PNG、component-sets/ が保存されます。以前の実行で作成されたファイルは残るため、別のデザインで同じフォルダーを再利用しないでください。
3. 参照画像を読み取り、ページのセクションを一覧にします。
4. コンポーネントを計画します。 繰り返されるセクションごと、または component 名ごとに1つのコンポーネントを作成します。各コンポーネントのバリエーションの選択肢は、componentSets[name].propValues で確認してください。
5. トークンを一度だけマッピングします。 ページで使用する各トークンキーを CSS 変数またはテーマ値に割り当てるテーマファイルを1つ作成します。各要素に16進数の値をコピーしないでください。
6. セクションごとに構築します。 layout を flex に対応付けます：direction、gap、padding、width、height、grow、align、justify。絶対配置は layout.position が absolute の場合に限って使用し、親要素を基準に left と top を指定します。
7. text からテキストを描画します。 textRuns がある場合は、ベースのタイポグラフィトークンに基づいて各 run を順番に描画し、text は再度描画しないでください（ビジュアルの詳細を解釈するを参照）。
8. ベクターをビューポートに合わせて配置します。 各ベクターについて、svgAssetsFolder から svgPathInAssetFolder で指定されたファイルを読み込みます。svgViewport.x と y（値がない場合は0）の位置に配置し、svgViewport.width と height に合わせてサイズを設定します。ノードのサイズに合わせて引き伸ばさないでください。
9. 画像の塗りつぶしに対応します。 写真やスクリーンショットなど、ノードで画像の塗りつぶしが使用されている場合は、get_image_fills を呼び出してダウンロード URL を取得します。
10. 上記の説明に従って、参照画像とビルド結果を照合します。
11. 対象のスタック、ブレークポイント、期待される出力が不明な場合は、推測するのではなく質問してください。

コンポーネントファイルの解決

• root.file、componentSets[name].file、および index.json 内の file エントリーは、componentSetsFolder からの相対パスです。場所を推測せず、このフォルダーに結合してください。
• 名前をファイル名にする際は、A–Z、a–z、0–9、_ 以外の文字が連続する箇所を、それぞれ1つの - に置き換えます。たとえば、Variant=Start 1, Color=Default は Variant-Start-1-Color-Default.json に、ノード 7:770 は 7-770.json になります。
• componentSets のキーは、記載どおりに使用してください。キーには、headline-combo [zd1Yd…/3574:6] のようなライブラリ参照が角括弧内に含まれる場合があります。キーからパスを組み立てず、file の値を読み取ってください。

注意点

• Root node … not found：ノード ID が間違っているか、ファイルを読み取れません。URL の node-id=519-8870 を 519:8870 に変換し、そのファイル内にノードが存在することを確認してください。
• 呼び出しの繰り返し：サーバーは同じ入力のデザインを5分間キャッシュします。再取得せず、最初の応答を保持してください。includeComponentVariants、resolveVariables、認証情報を変更すると再取得されます。
• interactions は、プロトタイプのホバーやクリックの対象を示します。ビルドでその動作が必要な場合を除き、無視してください。

はじめに

多くのコードエディターやその他の AI クライアントでは、MCP サーバーを管理するために設定ファイルを使用します。

このサーバーには Node.js 18 以降が必要です。

tmegit-figma-to-code-mcp サーバーは、設定ファイルに以下を追加して設定できます。

MacOS / Linux

{
  "mcpServers": {
    "Figma To Code MCP": {
      "command": "npx",
      "args": ["-y", "@tmegit/figma-to-code-mcp", "--figma-api-key=YOUR-KEY", "--stdio"]
    }
  }
}

Windows

{
  "mcpServers": {
    "Figma To Code MCP": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@tmegit/figma-to-code-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}

または、env フィールドで FIGMA_API_KEY と PORT を設定できます。

HTTP モード

--stdio を省略すると、/mcp で Streamable HTTP を、/sse でレガシー SSE を提供し、メッセージは /messages に送信されます。同時に接続するクライアントはそれぞれ独立した MCP セッションを持ち、1 つの接続を閉じてもほかの接続は閉じません。ライブラリー変数の事前取得は、同じ認証情報を設定したセッション間で共有されます。

組み込み用途では、startHttpServer(host, port, server) に、このパッケージの createServer が返すサーバーを引き続き渡せます。カスタムの McpServer を使う場合は、同時に接続するクライアントに対応するため、3 番目の引数にセッションごとのファクトリーを渡してください。単一の外部インスタンスは、引き続き単一セッションとして動作します。

createServerFactory(auth, options) は、共有設定を一度だけ準備します。カスタムツールを追加する場合は、ファクトリーが返すすべてのサーバーに登録してください。渡された単一のインスタンスに追加した登録は、生成されたほかのサーバーにはコピーされません。カスタムの非同期ファクトリーは、保留中の接続をクリーンアップしてシャットダウンを完了できるよう、処理が完了する必要があります。

デフォルトのホストは 127.0.0.1 です。これらのエンドポイントではクライアント認証を行いません。認証済みプロキシなしで、信頼できないネットワークに公開しないでください。

設定

サーバーは、CLI フラグと環境変数から設定を読み込みます。両方が設定されている場合は、CLI フラグが優先されます。

オプション	CLI	環境変数	デフォルト
Figma API キー	--figma-api-key	FIGMA_API_KEY	必須
Figma OAuth トークン	--figma-oauth-token	FIGMA_OAUTH_TOKEN	未設定
ポート	--port	FIGMA_TO_CODE_MCP_PORT または PORT	3333
ホスト	--host	FIGMA_TO_CODE_MCP_HOST	127.0.0.1
出力形式	--json	OUTPUT_FORMAT	yaml
画像ツールとノード PNG をスキップ	--skip-image-downloads	SKIP_IMAGE_DOWNLOADS=true	false
SVG 出力ディレクトリー	--svg-output-dir	FIGMA_SVG_OUTPUT_DIR	一時ディレクトリー
ライブラリー変数の事前取得	--library-file-keys	FIGMA_LIBRARY_VARIABLE_PREFETCH_FILE_KEYS	未設定
キャッシュパス	--library-cache-path	FIGMA_MCP_CACHE_PATH	一時キャッシュファイル
キャッシュ TTL	n/a	FIGMA_MCP_CACHE_TTL_MS	7 days
キャッシュを強制更新	n/a	FIGMA_MCP_REFRESH_CACHE	オフ

注記：

• --library-file-keys と FIGMA_LIBRARY_VARIABLE_PREFETCH_FILE_KEYS には、Figma ライブラリーファイルキーをコンマ区切りで指定します。
• FIGMA_MCP_CACHE_PATH には、JSON ファイルまたはディレクトリーを指定できます。サーバーはキャッシュされたライブラリー変数を分離するため、.json の前に認証情報のフィンガープリントを付加します。たとえば、ディレクトリー内の figma-mcp-library-cache.<fingerprint>.json のようになります。スコープのない既存のキャッシュファイルは、サーバー起動時に再利用されません。
• ライブラリーキャッシュは、ライブラリーファイルキーが設定されている場合にのみ使用されます。
• FIGMA_MCP_REFRESH_CACHE を設定すると、キャッシュファイルが存在する場合でも、起動時に再取得します。

.env の例：

FIGMA_API_KEY=your_figma_pat
# prefetch variables (tokens etc) from specific library files on startup to avoid T2 calls during design fetch
FIGMA_LIBRARY_VARIABLE_PREFETCH_FILE_KEYS=abc123,def456
FIGMA_MCP_CACHE_PATH=./cache
FIGMA_MCP_CACHE_TTL_MS=604800000
# Uncomment to force cache refresh on next startup
# FIGMA_MCP_REFRESH_CACHE=1

API 呼び出しとレート制限

デザインキャッシュにヒットしなかった場合、get_figma_design は次の API 呼び出しを行うことがあります。

エンドポイント	ティア	呼び出されるタイミング
GET /v1/files/{fileKey}/nodes	T1	ベクタージオメトリを含む、指定されたデザインノードの取得
GET /v1/images/{fileKey}	T1	指定されたノードを 1x PNG としてレンダリング。失敗しても処理は続行されます
GET /v1/files/{fileKey}/variables/local	T2	resolveVariables=true の場合
GET /v1/files/{fileKey}/comments	T2	コメントの取得を試行。失敗しても処理は続行されます
GET /v1/components/{key}	T3	どの一覧にもまだ含まれていないコンポーネントキーのライブラリを検出する場合
GET /v1/files/{fileKey}/components	T3	このファイルと検出された各ライブラリの公開済みコンポーネントを、それぞれ一度一覧表示
GET /v1/files/{libFileKey}/nodes	T1	ライブラリごとにバッチ処理して、ソースコンポーネントの定義を取得

リクエスト数は、一意なコンポーネントキー、ライブラリ、ノードのバッチ数、再試行の数によって異なります。複数のライブラリのコンポーネントに対応しています。ライブラリのメタデータを取得できない場合は、利用可能なインスタンスデータにフォールバックします。

Figma の各ティアに応じてリクエスト間隔を調整し、Professional Dev/Full シートでは、ティア 1、2、3 の 1 分あたりの上限（それぞれ 10、25、50 リクエスト）を超えないようにします。それでも Figma が 429 を返した場合、そのティアのみ Retry-After の時間だけ一時停止し、最大 3 回までリクエストを再試行します。ネットワークレベルで失敗した GET は、curl を使って一度再試行します。これは企業プロキシ経由の接続に役立ちます。再試行は同じリクエスト枠で行われるため、ティアの予算では 1 回としてカウントされます。

互換性のあるデザインキャッシュにヒットした場合、これらの Figma 呼び出しは回避されますが、ノード PNG を含むアセットは引き続き指定されたディレクトリにエクスポートされます。PNG は Figma の画像 URL からダウンロードされますが、これは Figma API 呼び出しではありません。認証情報や結果に影響するオプションを変更した場合、互換性のないデザインレスポンスは再利用されません。

実効スタイルは、ノード固有のオーバーライドを含むノードプロパティから読み取られます。個別の /styles リクエストは行いません。ライブラリの既存の fetchStyles エクスポートと styleMap パラメーターは互換性のために引き続き利用できます。共有スタイル名は現在、デザインレスポンスに出力されません。

Professional プランの Dev/Full シートの場合：10 リクエスト/分（ティア 1）、25 リクエスト/分（ティア 2）、50 リクエスト/分（ティア 3）。

Star 履歴

謝辞

このプロジェクトは当初、GLips によるオリジナルの Figma Context MCP で探求されたアイデアに着想を得ています。 https://github.com/glips/figma-context-mcp

オリジナルのプロジェクトは、AI コーディングエージェントが利用しやすいよう Figma のデータを簡素化する Model Context Protocol（MCP）サーバーを提供しています。一方、この実装は異なるデータモデル、API、処理方法で大幅に再設計されており、独立したシステムとして扱う必要があります。