Figma MCP Server（figma-developer-mcp）で取れないプロパティがけっこうある話

はじめに

昨今のMCPサーバー提供の盛り上がりを受けて、Claude CodeやCursorなどのAIコーディングツールでFigmaのデザインデータを扱うとき、Framelink Figma MCP Server（npmパッケージ名: figma-developer-mcp）を使ってみようと思っている方は多いかもしれません。

しかしながら、結論から言うと、Figmaは2026年2月時点ではMCP Serverだけでは完全にデザイン通りの実装はできません。

フォント、色、回転、反転、不透明度、ブレンドモード……実装に必要なプロパティの多くがMCP Serverの返り値から欠落しています。MCP Serverには視覚的な把握（画像の書き出しやスクリーンショット）という強みがありますが、構造化されたプロパティデータについてはFigma REST APIを直接叩かないと話にならない場面が多いです。

この記事では、実際にソースコードを読んでわかった「MCP Serverで取れないもの」の一覧と、REST APIとの使い分けをまとめます。

検証環境

• figma-developer-mcp v0.6.4
• Figma REST API v1
• 検証日: 2026-02-10

figma-developer-mcp の概要

パッケージの同一性

以下はすべて同じパッケージです。検索するときに混乱しやすいので注意してください。

名称	文脈
figma-developer-mcp	npmパッケージ名
GLips/Figma-Context-MCP	GitHubリポジトリ
Framelink Figma MCP Server	公式名称

提供ツール

MCP Serverとして提供されるツールは2つだけです。

ツール名	用途
get_figma_data	ノードのレイアウト・スタイル・コンテンツ情報を取得
download_figma_images	画像アセットをSVG/PNGでダウンロード

データ処理の流れ

get_figma_dataは内部で以下の処理をしています。

1. Figma REST API (/v1/files/{key}/nodes) から生データを取得
2. 独自の簡略化処理でノードツリーを変換
3. YAMLまたはJSONで返却

問題はステップ2です。「簡略化」の過程で、実装に必要なプロパティが大量に落ちます。

MCP Serverで取得できないプロパティ一覧

ソースコード（dist/chunk-AAVXEDXX.js内の変換ロジック）を解析した結果です。

プロパティ	説明	MCP	REST API
characterStyleOverrides	テキスト内の文字単位のスタイルID配列	×	○
styleOverrideTable	スタイルIDごとのフォント・色・太さ定義	×	○
rotation	ノードの回転（ラジアン）	×	○
opacity	ノードの不透明度	×	○
blendMode	ブレンドモード	×	○
fills[].rotation	画像fillの回転角度	×	○
preserveRatio	アスペクト比固定フラグ	×	○
targetAspectRatio	元画像のアスペクト比	×	○
visible	表示/非表示	×	○

見ての通り、かなりの数が抜けています。「一部のプロパティが欠落」というレベルではなく、デザインの再現に必要な情報がごっそり欠けているという認識のほうが正確です。

特に影響が大きいケース

1. テキストの部分スタイル（最も深刻）

Figmaでは1つのテキストノード内で文字ごとにフォント・色・太さを変えられます。LPやバナーでは「超高価格でお買取!」のように、一部だけアクセントカラーにするケースは日常的です。

MCP Serverが返すのは style フィールド（テキスト全体のデフォルトスタイル）のみです。characterStyleOverrides と styleOverrideTable が欠落するため、部分スタイルの情報が完全に失われます。

# MCP Serverの返り値（簡略化済み）
style:
  fontFamily: "Noto Serif JP"     # ← デフォルトスタイル（実際にはどの文字にも適用されていない）
  fontSize: 81
  fontWeight: 400

# REST APIの返り値（完全）
style:
  fontFamily: "Noto Serif JP"     # ← デフォルトスタイル
characterStyleOverrides: [226, 226, 225, 225, 225, ...]
styleOverrideTable:
  "225":
    fontFamily: "Zen Maru Gothic"  # ← 実際に適用されているフォント
    fontWeight: 700
    fills: [{ color: { r: 0.106, g: 0.600, b: 0.545 } }]
  "226":
    fontFamily: "Zen Maru Gothic"
    fontWeight: 400

この例では、style.fontFamily が "Noto Serif JP" になっていますが、全文字に characterStyleOverrides が適用されており、実際のフォントは "Zen Maru Gothic" です。MCP Serverの返り値だけを信じると、間違ったフォントで実装してしまいます。

これは実際に自分がやらかしたミスです。MCP Serverの style.fontFamily を見て「デスクトップでは明朝体に変わるのか」と判断して実装し、Figma UIのスクリーンショットで指摘されて初めて気づきました。

2. 水平反転（Horizontal Flip）

Figmaで要素を水平反転すると、内部的には以下のように表現されます。

{
  "rotation": 3.141592653589793,
  "fills": [{
    "rotation": 360.0,
    "scaleMode": "FILL"
  }]
}

ノードに rotation: π（180°回転）、画像fillに rotation: 360°（=0°）を設定することで水平反転を実現しています。MCP Serverでは rotation が返らないため、反転の有無が判別できません。

CSSでの対応は transform: scaleX(-1) または Tailwindの -scale-x-100 です。

3. 非表示レイヤー

Figmaデザインにはパディングガイドなどの補助レイヤーが visible: false で配置されていることがあります。MCP Serverではこのフラグが返らないため、実装不要なレイヤーと実装すべきレイヤーの区別がつきません。

不要な要素まで実装してしまう、あるいは必要な要素を見落とすリスクがあります。

MCP Server と REST API の使い分け

両者は得意分野が明確に違います。対立するものではなく、それぞれの強みを活かして併用するのが正しい使い方です。

MCP Serverが得意なこと

用途	説明
画像アセットの書き出し	download_figma_images でPNG/SVGをローカルに保存できます。nodeIdとimageRefを指定するだけで、クロップや書き出しスケールも対応しています
デザインの視覚的な把握	ノードツリーの全体構造をYAML/JSONで俯瞰できます。「どのレイヤーがどこにあるか」をざっくり掴むのに便利です
レイアウトの大枠確認	位置（absoluteBoundingBox）やサイズは返るので、要素の配置関係は把握できます

REST APIが得意なこと

用途	説明
テキストの部分スタイル	characterStyleOverrides / styleOverrideTable で文字単位のフォント・色・太さが取れます
回転・反転	rotation でノードの回転角度、fills[].rotation でfill内の回転が取れます
表示/非表示の判別	visible フラグでガイドレイヤー等の実装不要な要素を除外できます
不透明度・ブレンドモード	opacity, blendMode など視覚効果に関わるプロパティが全て取れます
画像のscaleMode	FILL（object-cover）か FIT（object-contain）かを正確に判別できます

一言で言うと

• MCP Server: 「見る」「書き出す」が得意。視覚的な確認と画像アセットの取得に使います
• REST API: 「読む」が得意。実装に必要な正確なプロパティ値の取得に使います

REST APIの叩き方

ノード単位でデータを取得

curl -s \
  -H "X-Figma-Token: YOUR_PERSONAL_ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/{file_key}/nodes?ids={node_id}" \
  | python3 -m json.tool

パラメータ

パラメータ	説明	例
file_key	FigmaファイルURL内のキー（figma.com/design/<ここ>/...）	IS5vRNrxqXj8JBYcCpUKMl
node_id	ノードID（URLの node-id パラメータ、- を : に変換）	44:134

実用例: テキストの部分スタイルを取得

curl -s \
  -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$FILE_KEY/nodes?ids=44:134" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
node = data['nodes']['44:134']['document']

def find_text_nodes(n):
    if n.get('type') == 'TEXT':
        print(f\"Node: {n['name']} (id: {n['id']})\")
        print(f\"  characters: {n.get('characters')}\")
        print(f\"  default font: {n['style']['fontFamily']}\")
        overrides = n.get('styleOverrideTable', {})
        for sid, s in overrides.items():
            print(f\"  override {sid}: {s.get('fontFamily')} {s.get('fontWeight')} {s.get('fontStyle')}\")
        print()
    for child in n.get('children', []):
        find_text_nodes(child)

find_text_nodes(node)
"

推奨ワークフロー

1. MCP Server でデザインの全体像を把握
   - get_figma_data でノード構造・位置・サイズを確認
   - download_figma_images で画像アセットを書き出し

2. REST API で詳細プロパティを取得
   - テキストの部分スタイル (characterStyleOverrides / styleOverrideTable)
   - 回転・反転 (rotation)
   - 表示/非表示 (visible)
   - 不透明度 (opacity)
   - ブレンドモード (blendMode)

3. Figma UIで目視確認
   - REST APIでも判断しにくい情報（コンポーネントのオーバーライド状態など）
   - レイヤー間の重なり・マスク効果の視覚的確認

プロパティデータに関しては、ステップ2で取得する情報のほうが実装に直結するケースが多いです。場合によってはREST APIメインで進めたほうが効率的かもしれません。

まとめ

figma-developer-mcp（Framelink）は、画像の書き出しやデザインの視覚的な把握に便利なツールです。ただし、get_figma_data の返り値を「Figmaの全情報」だと思い込むと痛い目を見ます。フォント、色分け、回転、反転など、デザイン再現に不可欠なプロパティデータが簡略化の過程で消えています。

• 見る・書き出す → MCP Server
• 正確なプロパティを読む → REST API

この使い分けが、現時点での現実解です。

参考リンク

• figma-developer-mcp (npm)
• GLips/Figma-Context-MCP (GitHub)
• Figma REST API ドキュメント
• Figma MCP Server 公式ドキュメント