figma-mcp

figma-codekit-mcp

以前のパッケージ名からアップグレードする場合：MCP クライアントのコマンドでパッケージを npx -y figma-codekit-mcp@latest に置き換えてください。既存の環境設定と保存データは引き続き互換性があります。

Figma → デザインとの照合まで行うコード。

多くの Figma-to-code ツールは、生成した時点で処理を終えてしまいます。JSX を渡して、そのまま立ち去るのです。生成結果をレンダリングしてフレームと比較することはないため、仕上がりは「あと少し」の段階で止まり、午後いっぱいをパディングの目視調整に費やすことになります。

この MCP サーバーは、そのループを完成させます。フレームを決定論的に（LLM も、レイアウトの幻覚も使わずに）自己完結型の HTML に変換し、Chromium でコードをレンダリングして、Figma の参照画像とのピクセル差分を取り、すべての要素のボックスを測定して、不足しているものや配置がずれているものをエージェントに正確に伝えます。エージェントはコードを編集し、再度検証を呼び出して、差分がアンチエイリアスの限界に達するまで繰り返します。

Figma の参照画像	最初の試行 — 5.18% のずれ	ピクセル差分	収束後 — 0.00%

これらは npm run example の実際の生成物です。このコマンドは、API キーなしで最初から最後までループを実行します。このデモの generate コールバックは、LLM の代わりとなるスクリプトなので、ループの仕組みをありのままに示します。測定は実際に行いますが、「モデル」は実際のものではありません。

検証ステップが重要な理由

Figma のノードツリーから分かるのは、デザイナーが指定した内容です。ブラウザーが CSS を使って実際にどう表示するかは分かりません。両者は頻繁に食い違います。たとえば、折りたたまれる flex の gap、フォールバックされるフォント、親要素からはみ出す絶対配置の子要素などです。それを確かめる唯一の方法は、レンダリングして確認することです。

figma_verify は、検証のたびにエージェントへ3つの独立したシグナルを返します。

• ピクセル差分 — 全体の不一致率と、最も大きくずれている領域を示すため、どの程度、どこが違うのかが分かります。
• 要素のバウンディングボックスの IoU — すべての IR ノードに data-ir-id を付与し、実際の DOM 上で測定して、Figma のボックスと照合します。これにより、「左下がずれている」が「CTA ボタンがない」や「価格ラベルが40px低い」といった具体的な指摘に変わります。
• 描画順とクリッピング — Figma では子要素が奥から手前の順に並ぶため、ノードの先行順インデックスがそのまま描画順になります。サンプルグリッド上で elementsFromPoint を使うと、実際に重なり合う要素の描画順を取得できます。これにより、ほかの2つのシグナルでは仕組み上検出できない種類のバグを見つけます。要素は存在し、ボックスも正しいのに、重なり順が逆になっている、またはデザインでははみ出している要素が祖先要素の overflow によって切り取られている、といった問題です。どちらもボックスの位置は変わらず、高さのあるフレームでは差分率にもほとんど影響しませんが、写真の上に描かれるべき装飾オーバーレイが写真の下に描かれているのは、見る人が真っ先に気づく問題です。WRONG STACKING / OVER-CLIPPED として報告され、ピクセル差分が収束した後も報告されます。

ツール

ツール	機能	ネットワーク
figma_convert	フレームを取得し、自己完結型の HTML と ir.json、データ URI として埋め込まれたアセット、reference.png を生成します。オプションで react: true（コンポーネントと、インポートする components/）や next: true（実行可能な App Router プロジェクト）、レスポンシブ版も指定できます。	Figma API（キャッシュ済み）
figma_verify	Chromium で HTML をレンダリングし、参照画像とピクセル差分を比較し、すべての要素を IoU でチェックします。描画順とクリッピングを確認し、対象を絞った修正指示を返します。	なし
figma_inspect	IR をインデント付きのアウトライン（ロール、ボックス、レイアウト、テキスト、トークン）として出力し、フィルタリングできます。生の Figma JSON をコンテキストに流し込まずに、構造を確認できます。	なし

レスポンシブ出力は、デザインで実際に指定されている内容に依存します

responsive: true は Figma のサイズ指定を読み取ります。FILL は flex／100% に、HUG は fit-content に、FIXED は px のままになります。これはデザイナーが Auto Layout を使用した箇所に限られます。

ルートに Auto Layout がないフレームはキャンバスです。すべての子要素は 1440px のアートボード上の座標に position:absolute で配置されています。調整できるものはないため、ルートを width:100% にしても リフローは起きません。子要素はキャンバス上の座標に固定されたままなので、右側が overflow:hidden の下に消えます。 これは、ズームするとページが崩れるように見えます。

このようなフレームでは、コンバーターは正確なキャンバスを保持してビューポートに合わせて拡大縮小するため、 幅やズームレベルが変わってもデザインは崩れません（0.5x までは対応し、それを下回るとページがスクロールします）。 figma_convert が使用した方式を通知します。比例拡大縮小ではなく実際にリフローさせたい場合は、Figma で Auto Layout を追加してください。それがコンバーターに必要な手掛かりになります。

すべてのツールが返すのはファイルパスと数値であり、大きなデータの塊ではありません。変換した フレームは HTML だけで 100 KB を超えることがよくあります。これをツールの結果として渡すと、 エージェントのコンテキストを無駄に消費してしまいます。エージェントはファイルを直接読み取り、編集します。

Figma のレスポンスはフレームごとにキャッシュされるため、最初の figma_convert の後は、 レート制限中も含めて、一連の処理をオフラインで無料で実行できます。

クイックスタート

Figma の個人用アクセストークンが必要です：Figma → Settings → Security → Personal access tokens。スコープは File content: read です。

export FIGMA_TOKEN=figd_REPLACE_WITH_YOUR_TOKEN

Claude Code に追加します：

claude mcp add figma --env FIGMA_TOKEN=$FIGMA_TOKEN -- npx -y figma-codekit-mcp@latest

または、JSON 設定を読み込む任意の MCP ホストの場合：

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-codekit-mcp@latest"],
      "env": { "FIGMA_TOKEN": "figd_REPLACE_WITH_YOUR_TOKEN" }
    }
  }
}

次に、エージェントで Figma からフレームのリンクをコピーし（フレームを右クリック → Copy link to selection）、*「このフレームを変換し、収束するまで検証してください」*と伝えます。

セットアップの確認

FIGMA_TOKEN=$FIGMA_TOKEN npx -y figma-codekit-mcp@latest --check

Node、トークンが見つかったかどうか（値は表示せず、保存場所のみ）、Figma がトークンを受け入れるかどうか、 Chromium の figma_verify レンダリング環境がインストールされているかどうかを確認し、 READY または修正が必要な内容を出力します。終了コードが 0 であれば、3 つのツールすべてが動作します。 Chromium が見つからない場合（ダウンロードをスキップした、または CI の場合）は、 npx -y figma-codekit-mcp@latest --install-browser でインストールしてください。

Windows

npx は npx.cmd に解決されますが、一部の MCP ホストではこれを直接起動できません。 サーバーの起動に失敗した場合は、明示的に shim を指定してください：

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "figma-codekit-mcp@latest"]
}

処理の流れを具体的に

figma_convert  →  generated.html, reference.png, ir.json   (deterministic, no LLM)
      ↓
figma_verify   →  "NOT CONVERGED — 4.93% of pixels differ.
                   Elements: 22/26 match — 1 missing, 3 misplaced.
                   MISSING: button 'Get started'
                   MISPLACED: h1 'Pricing plan' — 6px too high"
      ↓
  agent edits generated.html
      ↓
figma_verify   →  "CONVERGED — 0.31% of pixels differ (threshold 2.00%)."

調整のループはサーバー内部の LLM ではなく、呼び出し元のエージェントを通じて実行されます。 そのため、ANTHROPIC_API_KEY は不要で、2 つ目のモデルへの課金も発生せず、エージェントはこれまでに試した内容の コンテキストをすべて保持できます。ヘッドレスの調整ループ（src/refine/）も、ライブラリとして使用するために 引き続き利用できます。

エージェントなしでループを見る

同じパイプラインには、1ページ構成のローカル Web フロントエンドもあります。画面は左右に分かれ、左側がチャット、右側が生成されたアプリです。フレームのリンクを送ると、何を作成するか（HTML、React、Next.js のいずれか）、また完全一致かレスポンシブかを尋ね、その後、変換、レンダリング、差分比較を目の前で行います。右側のペインには、実行中のアプリ、そのソースファイル、検証結果の数値、ピクセル差分が表示されます。

npm run site        # http://localhost:5173

同じ .figma-token と .figma-cache/ を使用するため、すでに変換したフレームは約1秒でオフライン再実行できます。エージェントに渡す前に、フレームが問題なく変換されるかを確認したい場合や、「デザインに対して検証済み」とはどういう意味かを説明ではなく実際に見せたい場合に便利です。詳細は site/README.md をご覧ください。

設定

変数	用途
FIGMA_TOKEN	必須です。プロジェクトディレクトリ内の .figma-token ファイルからも読み込まれます。FIGMA_API_KEY もエイリアスとして使用できます。
FIGMA_MCP_CACHE_DIR	変換したフレームのキャッシュ先です。デフォルトは、サーバーの起動元ディレクトリ内の .figma-cache/ です。
ANTHROPIC_API_KEY / GEMINI_API_KEY	任意です。ヘッドレスのリファインループでのみ使用します。MCP サーバーが LLM を呼び出すことはありません。
FIGMA_MCP_SKIP_BROWSER_DOWNLOAD=1	インストール時の Chromium のダウンロードをスキップします。figma_convert と figma_inspect は引き続き動作しますが、figma_verify は動作しません。

.env.example をご覧ください。埋め込みアセットを含むキャッシュ済みフレームは数十メガバイトになるため、プロジェクトの .gitignore に .figma-cache/ を追加してください。

対応していないこと

制約はバグではなく Figma の仕様によるものです。率直に説明します。

• Enterprise プランでない場合、デザイントークンはリテラル値に解決されます。 Figma Variables REST API は Enterprise 専用です。利用できない場合、色や間隔は var(--color-surface) ではなく、正確な値として出力されます。それ以外はすべて動作します。
• コンポーネントの prop バインディングには Code Connect が必要です。 コンポーネントは名前で照合して報告されますが、どのインスタンスプロパティがどの値を決定したかは API から取得できません。
• 差分には下限があります。 アンチエイリアスやフォントのヒンティングにより、完全に一致していても比率は約 0.5～1.5% になります。そのため、threshold のデフォルト値は 2% です。0 を目指すのは、レンダリングノイズを追いかけることになります。
• 一度に処理できるのは1つのフレームです。 設計上、ファイル全体のクロールには対応していません。これにより、トークン消費と Figma のレート制限への負荷を予測しやすくしています。

ライブラリとして使う

検証ループはフレームワークに依存せず、MCP レイヤーも必要ありません。

import { verifyLoop } from 'figma-codekit-mcp';
import fs from 'node:fs';

const result = await verifyLoop({
  initialCode: firstPassHtml,
  referencePng: fs.readFileSync('frame.png'),
  ir,                                   // enables element-level IoU findings
  viewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
  threshold: 0.02,
  maxIterations: 5,
  generate: async ({ code, correction }) => callYourModel({ code, correction }),
});

console.log(result.converged, result.diffRatio);
fs.writeFileSync('diff.png', result.bestDiffPng);

このループは、これまでに確認された最良のイテレーションを保持するため、その後に回帰が発生しても結果が悪化することはありません。HTML 文字列ではなく、開発サーバー上の React コンポーネントを検証するには、render: () => renderUrl('http://localhost:3000/preview', viewport) を渡します。

開発

git clone https://github.com/Mehmoodqureshi/figma-codekit-mcp.git
cd figma-codekit-mcp
npm install          # also downloads Chromium via postinstall
npm test             # full chain against a mocked Figma API — no token, no network
npm run example      # the verify loop end to end; watch the diff ratio fall
npm run serve        # run the MCP server on stdio

パス	役割
src/mcp/	MCP サーバー、Figma REST ソース、フレーム読み込み、アセットのエクスポート
src/ir/	Figma ノードツリー → 正規化された IR（ロール、ボックス、自動レイアウト、スタイル、トークン）
src/codegen/	IR → HTML / React / CSS
src/render.js src/diff.js src/elementDiff.js src/paintOrder.js	Playwright によるレンダリング、ピクセル差分、バウンディングボックス IoU、重なり順序とクリッピング
src/correction.js src/verifyLoop.js	差分を修正指示に変換し、ループを実行
src/refine/	オプションのヘッドレス LLM リファイナー（Anthropic、Gemini）
example/	実行可能なデモとオフラインテストスイート

example/ はテストスイートも兼ねています。npm test を実行すると、レート制限の処理や回転・ミラー変換を含め、モックの Figma REST API に対して loadFrame → figmaToIR → generateHtml の一連の処理を実行します。トークンもネットワークもブラウザーも不要なので、プッシュのたびに CI で実行できます。

関連項目

• MCP Browser Extension (mcp-browser-extension)：すべてのドメインを拒否する許可リストを設定し、Claude、Cursor、その他の MCP エージェントが、すでにログインしている Chrome を使えるようにします。

ライセンス

MIT © Mehmood Ur Rehman Qureshi