figma-context-mcp

Figma Context MCP

Figma Context MCP（Framelink とも呼ばれます）のエキスパートガイドです。429 レート制限によるロックアウトを防ぐ、効率的な API 使用パターンを説明します。

ツール

ツール	目的	API ティア
get_figma_data	ファイル／ノードの構造、レイアウト、コンポーネントを取得します	ティア 1（最も制限が厳しい）
download_figma_images	特定のノードの PNG／SVG レンダリングをエクスポートします	ティア 2～3

重要：レート制限

Figma ではプランごとにレート制限が適用されます。制限は、あなたのプランではなく、ファイル所有者のプランに基づきます。

ティア	Starter	Pro	Org
ティア 1（ファイル）	10／分	15／分	20／分
ティア 2（画像）	25／分	50／分	100／分
ティア 3	50／分	100／分	150／分

View／Collab シートで利用できるティア 1 の呼び出しは、月あたり 6 回のみです。Starter／無料プランのユーザーが所有するファイルにアクセスする場合、そのユーザーの制限が適用されます。

429 によるロックアウトは4～5 日間続くことがあります。予防が不可欠です。

ワークフロー：メタデータ優先のパイプライン

最初にすべてを取得しないでください。 ほとんどの処理を API 呼び出し 2～3 回、データ量 500 KB 未満に抑えるため、次のパイプラインを採用してください。

1. ファイル全体ではなく、対象のノードから開始する

ユーザーが figma.com/design/FILEKEY/Name?node-id=123-456 のような Figma URL を指定した場合は、必ず nodeId を抽出して渡してください。特定のノードを指定できる場合、ファイル全体を取得しないでください。

get_figma_data(fileKey="ABC123", nodeId="123-456", depth=2)

2. 深さを最小限にする

ツリーの走査範囲を制限するため、必ず depth を設定してください。

• depth=1：最上位のフレームのみ（レイアウト構造、コンポーネント名）
• depth=2：フレームと直下の子ノード（通常、コード生成には十分です）
• depth=3：推奨される最大値。ネストされたオートレイアウトが必要な場合のみ使用してください

省略した場合のデフォルト：API はサブツリー全体を返します。複雑なフレームに子ノードが 50～200 個以上あると、数 MB に達することもよくあります。これが 429 エラーの最大の原因です。

3. 追加取得の前にローカルで分析する

最初の応答を受け取ったら、次の作業を行います。

• 詳細が本当に必要な子ノードを特定します（非表示、装飾用、ライブラリ参照のノードは除外します）
• デザインのトークン（色、間隔、タイポグラフィ）は、追加の呼び出しをせず、応答から直接抽出します
• すでに取得した情報を使ってコンポーネント構造を組み立てます

4. 必要な場合にのみ、より深いノードを取得する

特定の子ノードにさらに詳しい情報が必要な場合は、そのノードのみを取得してください。

get_figma_data(fileKey="ABC123", nodeId="child-node-id", depth=1)

5. 画像のダウンロードは最後に、小さなバッチで行う

実際に必要な最終的な重複除去済みのビジュアルアセットのみをリクエストしてください。

• imageRef で重複を除去します。複数のノードが同じ塗りつぶし画像を参照している場合があります
• 1 回の呼び出しにつき、5～10 個のノードをまとめて処理します
• ユーザーが @2x／@3x のアセットを特に必要としている場合を除き、pngScale=1 を使用します

download_figma_images(
  fileKey="ABC123",
  nodes=[{nodeId: "1:2", fileName: "hero", ...}],  # max 5-10 per call
  localPath="./assets",
  pngScale=1
)

429 が発生した場合

診断と復旧手順については、references/rate-limit-recovery.md を参照してください。

簡単なチェックリスト：

1. すべての Figma API 呼び出しを直ちに停止します。追加の呼び出しによってロックアウト期間が延びます
2. ファイルが Starter／無料プランのユーザーによって所有されているか確認します（制限は所有者ごとに適用されます）
3. ユーザーが Pro／Org プランの場合は、自分のワークスペースにファイルを複製するよう提案します
4. 再試行する前に、Retry-After ヘッダーで指定された時間だけ待ちます
5. 再試行時は、上記の最小深度パイプラインを使用します

よく使うパターン

デザインからコードを生成する（単一コンポーネント）

1. 特定の nodeId と depth=2 を指定して get_figma_data を実行します（1 回）
2. 応答からコードを生成します。コンポーネントにラスターアセットが含まれない限り、画像の呼び出しは不要です
3. 画像が必要な場合：ラスターの塗りつぶしのみを対象に download_figma_images を実行します（1 回）
4. 合計：API 呼び出し 1～2 回

デザインからコードを生成する（ページ全体）

1. ページの nodeId と depth=1 を指定して get_figma_data を実行し、フレームの一覧を取得します（1 回）
2. 重要なフレームを 2～3 個特定します
3. 各重要フレームに対して depth=2 を指定し、get_figma_data を実行します（2～3 回）
4. トークンをローカルで抽出し、重複のないラスターアセットのみをダウンロードします（1 回）
5. 合計：API 呼び出し 4～5 回

デザイントークンのみを抽出

1. get_figma_data を nodeId + depth=2 で呼び出します（1 回）
2. レスポンスから色、タイポグラフィ、間隔を解析します。画像の呼び出しは不要です
3. 合計：API 呼び出し 1 回

アンチパターン

パターン	問題	対策
depth を省略する	サブツリー全体（数 MB のデータ）が返されます	必ず depth=2 以下を設定します
nodeId を省略する	ファイル全体を取得します	必ず URL から nodeId を抽出します
画像をすべて事前にダウンロードする	画像リクエストが集中し、Tier 2 の上限に達します	重複を除いた最終セットのみをダウンロードします
429 で再試行する	ロックアウトの時間が延びます	停止し、Retry-After を待ってから、最小限の呼び出しで再開します
ライブラリコンポーネントを取得する	リモートライブラリのノードによって、余分な API 呼び出しが発生します	初回レスポンスのローカルコンポーネントデータを使用します