figbridge

Figbridge

Figma ↔ コードを、双方向につなぎます。 無料、オープンソース、ローカルで動作し、コミュニティのために作られています。

Figbridge は、Figma プラグインとローカル MCP サーバーです。任意のファイルでプラグインを開き、Live bridge をオンにすると、MCP に対応したエージェント（Claude Desktop、Claude Code、Cursor、Continue、Cline など）が、127.0.0.1 経由で画面、トークン、コンポーネントを読み取り、URL 全体を Figma にインポートし、インポートしたデザインを監査し、ソースとの差分を確認して、ソースリポジトリ向けのパッチを出力できます。

┌──────────┐   postMessage   ┌──────────┐   HTTP + SSE    ┌───────────────┐     stdio     ┌──────────────┐
│  Figma   │ ──────────────▶ │  Plugin  │ ──────────────▶ │  MCP Server   │ ◀──────────── │  AI agent    │
│  Desktop │                  │   UI     │   :7331/push    │  (localhost)  │   tools/call  │  (Claude …)  │
└──────────┘                  └──────────┘                 └───────────────┘               └──────────────┘

その理由

Figbridge はコミュニティのニーズに応えるために作られました。無料、オープンソース、ローカルで動作し、ウェブサイトのキャプチャからソースへのパッチ作成まで役立ちます。

Figbridge の特長：

• 無料。 MIT ライセンスです。すべての処理をお使いのマシン上で実行します。
• アカウントもトークンも不要。 既存の Figma デスクトップセッションを使用します。
• 54 個の MCP ツール。 読み取り、カタログ化、書き戻し、Lint、Figma コンポーネントとコードのマッピング（Dev シートなしで Code Connect を実現）、エージェントへの引き継ぎ用バンドルの作成、ライブ URL の Figma へのインポート、5 つの観点からのインポート済みデザインの監査、変更のパッチとしてのソースリポジトリへのラウンドトリップ、実行中のアプリをモックアップに合わせるビジュアル差分のクローズドループを実行できます。
• 待つ前にインポートを診断。 preflight_import は、完全なインポートの前に、ボット対策のページ、深い DOM、低解像度の画像、SVG の多いページ、ダウンロード可能なフォントアセットを検出します。
• 難しいページ向けのハイブリッドフォールバック。 import_url({ hybridSnapshot: true }) を使うと、ピクセル単位の忠実度が重要となる動画主体のサイトや生成サイトで、編集可能なレイヤーの下に全ページのスクリーンショット参照を配置できます。
• Chrome／Edge の現在のタブをキャプチャ。 chrome-extension/ を展開して読み込むと、表示中のビューポート、ページ全体、選択した要素、認証済みのタブ、localhost、ステージングページをローカルブリッジに直接送信できます。
• オフラインのエージェントバンドル。 get_agent_bundle は、ライブ MCP 接続がなくてもエージェントが使える zip（階層構造 · トークン · コンポーネント · AGENTS.md · CHANGES.md）を生成します。
• 決定論的。 LLM による書き換えはありません。選択した内容がそのまま反映されます。
• ライブ。 「Live bridge」をオンにすると、選択内容が変わるたびに自動で送信され、エージェントは現在の選択内容をすぐに取得できます。

インストール — 約 3 分

プラグインはまだ Figma Community に公開されていないため、リポジトリをクローンして入手します。MCP サーバーは npm から入手できます。

# 1. Get the Figma plugin (clone the repo)
git clone https://github.com/rudraptpsingh/figbridge

# 2. Patch Claude Desktop's MCP config
npx figbridge-mcp init

続いて：

1. Claude Desktop を終了して再起動します — MCP 設定は起動時にのみ読み込まれます。
2. Figma で、Plugins → Development → Import plugin from manifest… を選択し、上記のクローン内にある plugin/manifest.json を指定します。（初回のみ。）
3. 任意のフレームで Figbridge プラグインを実行し、Live bridge をオンにします。プラグインのヘッダーに緑色の点が表示されたら、ローカルブリッジに接続されています。フッターにポートが表示されます。
4. Claude に「figbridge が公開しているツールは何ですか？」と尋ねます — 40 個以上のツールが表示されるはずです。

ほかの MCP クライアント（Cursor、Cline、VS Code など）では、同じバイナリ npx figbridge-mcp を指定してください。

MCP レジストリ経由でのインストール

Figbridge は、公式の Model Context Protocol registry に io.github.rudraptpsingh/figbridge としても登録されています。レジストリに対応したクライアント（Claude Desktop、Cursor、VS Code）なら、設定を手動で編集せずに検出してインストールできます。

トラブルシューティング

Claude Desktop に "Server disconnected" と表示される場合や、ポート 7331 が使用中のままになる場合は、次を実行してください。

npx figbridge-mcp doctor

孤立した figbridge-mcp プロセスを終了し、使用中のポートを報告します。ブリッジは 7331 が使用中の場合、7332〜7340 に自動でフォールバックし、プラグインも同じ範囲を自動で確認します。そのため、「ポートが使用中」という理由で接続が妨げられることはありません。FIGBRIDGE_PORT=NNNN を指定すると、優先して使用する開始ポートを上書きできます。

POST /command 経由で Figma を操作するローカルエージェントの長時間セッションでは、永続ブリッジを実行してください。

npx figbridge-mcp bridge

ローカル HTTP+SSE ブリッジのみを起動し、標準入力が閉じた後も稼働し続けます。デスクトップやターミナルのツールが短時間のコマンドを起動する一方で、複数のエージェント操作を通して Figma プラグインとの接続を安定して維持したい場合に使用します。

更新

init は npx -y figbridge-mcp@latest を実行する設定を書き込むため、Claude Desktop を起動するたびに最新バージョンが取得され、新しいリリース後に何もする必要はありません。

設定に絶対パスが書き込まれる旧バージョン（≤ 0.1.1）をインストールした場合は、次のコマンドを一度実行して修復してください。

npx figbridge-mcp@latest update

現在インストールされているバージョンに固定したい場合（自動更新なし）は、npx figbridge-mcp init --pin を使用してください。npx figbridge-mcp --version を実行すると、インストールされているバージョンが表示されます。

MCP ツール

読み取り（8） — get_current_selection · get_last_export · list_history · get_tokens · bridge_status · diff_since · list_pages · list_frames

カタログ（8） — list_screens · list_components · describe_screen · export_app_spec · export_all_pages · list_assets · select_node · export_node

操作と引き継ぎ（5） — get_agent_bundle · clone_screen · recolor · apply_tokens · lint_ds

ブラウザー（11） — preflight_import（インポート前のリスクチェック。フォントのダウンロード URL を含む）、import_url（ライブ URL → Figma フレーム。オプションで hybridSnapshot のスクリーンショット参照を指定可能）、import_responsive_set（デスクトップ／タブレット／モバイル、およびオプションでライト／ダークテーマのキャプチャ）、import_url_batch（URL の一括インポート）、screenshot_url、probe_url、fingerprint_url、audit_interactions（ホバー／フォーカスの検出）、verify_text_fidelity、measure_fidelity、audit_regression（ベースライン URL と候補 URL のフロントエンド／UI 回帰監査）

柱 1 — 往復編集（2） — diff_to_source（インポートしたフレームとライブソース間のテキストノードごとのフィールド差分） · generate_patch（差分をソースディレクトリに対する最小限の HTML／JSX などのパッチに変換。スタイルの置き換えには、構造化された CSS ファイルのヒントが付属します）

柱 2 — デザインインテリジェンス監査（5） — audit_palette · audit_typography · audit_a11y（WCAG 2.x のコントラスト、ランドマーク、代替テキスト） · audit_whitespace（パディング／ギャップのリズム、4／8 グリッドへの準拠） · audit_mobile（複数ビューポートでのレスポンシブ監査：横スクロール、overflow-x、44px 未満のタッチターゲット、12px 未満のテキスト）

Code Connect（3） — connect_components（figbridge.connect.json の初期設定／編集：Figma コンポーネント → コードコンポーネントと props） · get_code_connect（マッピングされたコンポーネント、props、およびインスタンス用のすぐに貼り付けられる JSX スニペット） · lint_connect（CI ゲート：ファイル、エクスポート、props、リテラル値、Figma プロパティがすべて引き続き存在することを確認）。開発者シートなしでの Code Connectを参照してください。

柱 3 — モックアップに合わせる（3） — match_mockup（レンダー → 差分 → 調整を繰り返すループ：実行中のアプリと対象のモックアップをレンダリングし、ビューポートごとの視覚スコアに加えて、コピー／色／タイポグラフィ／間隔／エレベーション／アイコン／構造の差異を優先順位付きで列挙します。さらに、デザイン言語のスタイルフィンガープリントと、sourceDir を指定した場合は各項目で編集すべきソースファイルも返します） · diff_specs（レンダリングした URL またはキャプチャした spec JSON ファイル間の、正確で構造化されたフィールドレベルの差分） · map_components（アプリのソースツリーをインデックス化します。data-testid／コンポーネント → ファイルに加えてデザイントークンも対応付けるため、差分に変更すべきファイルと、リテラル値を置き換えるべきトークンが示されます）

Figma とのコンポーネント照合。 Figma エクスポーター（プラグインの export_frame または Figma MCP のスクリーンショット）で任意のバリアントをスクリーンショットにし、screenshot_url（width + height、fullPage: false）で同じサイズのコンポーネントをレンダリングしてから、両方を diff_images に渡します。スコア、SSIM、モンタージュ PNG が得られます。すべてのバリアントをレンダリングするキットページ（例：?kit ルート）を配信し、シート全体を実行するには match_mockup の対象として指定してください。 コード内のサイズ決定ルールを確認します。 デザインの HTML ビューとアプリの状態が一致している場合、リポジトリのルートを sourceDir として match_mockup または diff_specs に渡します。差分にはビューポートの x/y 座標とサイズが含まれます。FigBridge は data-testid と data-state（または figbridge.connect.json のコンポーネント名）を使ってソースファイルを特定し、近くにある JSX クラスを表示します。該当する寸法に一致する記述済みリテラルが 1 つだけある場合、codeChange は正確な行、現在のルール、推奨される置き換え内容を示します。それ以外の場合、編集箇所は未解決のままになります。また、Figma からエクスポートされた tokens.json 内の float 変数と、生成された v2Tokens.json を比較し、tokenDrift を報告します。スクリーンショットだけで確認できるのはピクセル比較のみです。また、写真や UI の状態が異なる場合、画面全体の一致を証明することはできません。

構造化差分では、アプリにバーやパネルが追加されても、一意の名前を持つ兄弟要素の対応関係を維持するようになりました。また、異なる明示的な data-state マーカーを報告し、指摘リストが上限に達した場合は省略された検出結果を開示します。比較可能な色、ジオメトリ、スタイルの値は、デフォルトで正確に報告されます。小さな数値差や JND 未満の色差を抑制するには、tolerant: true を設定します。不足または不完全な構造化比較がある場合、ピクセルスコアだけで合格にはなりません。2 つの URL では引き続き内容と状態を一致させ、検査可能なデザインエクスポートを用意する必要があります。FigBridge は PNG から Electron の DOM フィールドや Figma のトークン値を推測できません。

Electron のネイティブ状態。 diff_specs では、appUrl の代わりに appSpecPath を（また、mockupUrl の代わりに mockupSpecPath を）指定できます。対象の状態が落ち着いた後、実際の Electron Playwright ページをキャプチャします。mcp/src/dom-to-spec.js を読み込み、次に await page.evaluate(extractor) と await page.evaluate(() => window.domToSpec({ rootSelector: 'body', viewport: 1440, embedImages: false })) を実行し、その結果を JSON として保存します。Playwright による評価は、パッケージ化されたレンダラーの script-src 'self' ポリシーでも動作しますが、page.addScriptTag({ content: extractor }) はそのポリシーによってブロックされる場合があります。レンダリングされた Figma HTML の mockupUrl、ネイティブの appSpecPath、および sourceDir を指定して diff_specs を呼び出すと、正確な対応値とソース位置を取得できます。両側とも JSON ファイルとしてキャプチャすることもできます。各側で指定できるのは URL または spec パスのいずれか 1 つだけです。Figma の PNG でサポートされるのはピクセル比較のみです。正確な Figma フィールドには検査可能なエクスポートが必要であり、画面全体の判定には内容と状態の一致も引き続き必要です。

異なるレイヤーツリー。 ネイティブ DOM ツリーのネスト構造が Figma のレイヤー構造と一致しない場合は、diff_specs に anchors を渡します。各ペアでは、Figma ノード（構造化 Figma spec の mockupId または一意の mockupName）とアプリの data-testid を指定します。fields を使うと、['x','y','width','height'] など、実際に検査するプロパティにペアの対象を限定できます。FigBridge は両方の spec からビューポート上のジオメトリを比較し、アンカーごとの正確な差分をアプリのソースマッピングとともに報告します。coverage には、要求数、一意に照合された数、欠落または曖昧なアンカー数が表示されます。一致しないアンカーがあると、ok: true にはなりません。これは測定対象を限定した比較なので、証明したいプロパティを持つすべての領域にアンカーを追加してください。例：{ "name": "Action pill", "mockupId": "95:2956", "appTestid": "photo-toolbar-pill", "fields": ["x", "y", "width", "height"] }。Figma spec ノードには _figmaId と、ライブノードから読み取った値を含めることができます。スクリーンショットだけでは、それらの値を取得できません。

すべての監査は、モデル呼び出しを行わない、純粋で決定論的な測定です。計画ループにそのままフィードバックできる数値スコアと構造化された問題リストを返します。audit_regression は、UI の変更をリリースする前のローカル／CI ゲートとして使用できます。デスクトップ、タブレット、モバイル全体で、スクリーンショット、表示されないテキスト、レスポンシブ関連の問題の差分、CSS 機能の差分を比較します。

Chrome の現在のタブをキャプチャ

chrome-extension/ フォルダーには、認証が必要なページ向けの、展開済みの MV3 拡張機能が含まれています。

1. chrome://extensions を開き、デベロッパーモードを有効にして、chrome-extension/ フォルダーを展開済みの拡張機能として読み込みます。
2. Figbridge MCP を起動し、ライブブリッジを有効にして Figbridge Figma プラグインを開きます。
3. 拡張機能のポップアップを使って、表示中のビューポートを送信したり、ページ全体の DOM キャプチャを有効にしたり、ページ要素を選択したり、編集可能なレイヤーの下にビューポートのスクリーンショットを参照として含めたりできます。

ブラウザーでのキャプチャでは、各 Web サイトやプロジェクトを独自の Figma ページにまとめることができます。たとえば、Chrome Capture - Raycast や Chrome Capture - Localhost のように整理すれば、開いている 1 つの Figma ファイル内で個別のプロジェクトを見やすく管理できます。

この拡張機能は 127.0.0.1:7331..7340 にのみ送信し、ページデータをクラウドサービスに送信することはありません。

Dev シートなしで使う Code Connect

Figma Code Connect を使うには、Organization または Enterprise プランの Dev シートまたは Full シートが必要です。Figbridge は、コードと一緒にコミットするマップを使い、同じ役割をローカルで無料で実現します。

1. マップ — リポジトリ内の figbridge.connect.json。 Figma コンポーネントごとに 1 つのエントリーを記述します。

UI キットで、表示用フレーム内に別々のバリアントコンポーネントを配置している場合は、そのフレームを figma.nodeId として保持し、正確なコンポーネント ID を figma.variantNodeIds に列挙します。FigBridge はインスタンスのメインコンポーネント ID を読み取り、構造化差分の場合も含めて、対応するバリアントを解決します。似た名前から所有関係を推測することはありません。

{
  "version": 1,
  "fileKey": "WwO2ckSkwjOeusmEQwWrus",
  "imports": { "src/": "@/" },
  "components": [{
    "figma": { "fileKey": "WwO2ckSkwjOeusmEQwWrus", "nodeId": "59:944", "name": "Button",
               "properties": { "Style": { "type": "VARIANT", "options": ["Primary", "Secondary", "Quiet", "Destructive"] } } },
    "code":  { "source": "src/components/primitives/Button.tsx", "export": "Button",
               "import": "import { Button } from '@/components/primitives/Button'" },
    "props": {
      "variant":  { "figma": "Style", "type": "enum", "values": { "Primary": "primary", "Secondary": "secondary" } },
      "loading":  { "figma": "State", "type": "enum", "values": { "Loading": true } },
      "icon":     { "figma": "Icon", "type": "instance", "as": "component", "when": "Show icon", "importFrom": "lucide-react" },
      "children": { "figma": "Label", "type": "text" },
      "testId":   { "type": "static", "expr": "testId" }
    }
  }]
}

Prop type	Code Connect の対応	マッピング
enum	figma.enum	バリアント値 → prop 値（values。マッピングされていない値では prop が除外されます）。複数の行で 1 つのバリアントを読み取れます。例：State=Loading → loading、State=Disabled → disabled。
boolean	figma.boolean	boolean プロパティ → true／省略、または values を介したマッピング
text	figma.string	テキストプロパティ → 文字列 prop、または JSX の children
instance	figma.instance	インスタンススワップ → {Download}（as: "component"）または {<Download />}。importFrom を指定すると import が追加されます
static	—	固定の value、または Figma に対応するプロパティがない prop のための expr プレースホルダー

when は、Figma の boolean（"Show icon"）に基づいて任意の prop を有効にします。Figma の名前は #12:34 のサフィックスを除いて照合されます。任意の example テンプレートでは、{{props}}、{{children}}、{{propName}}、生の {{figma.Label}} 値を使用できます。これは、コードのコンポーネント構造が Figma と異なる場合（Figma ではセグメント、コードでは options を持つ Segmented）に使います。

2. 初期データを生成します。 connect_components を使うと、エントリーが自動で書き込まれます。コンポーネントの説明にある Code: src/…tsx の行、その Test id:（map_components インデックス経由）、またはコンポーネント名から、ファイルとエクスポートが特定されます。props は TSX から取得され、バリアント値は各 prop の文字列リテラル型のユニオンと照合されます。overwrite を渡さない限り、手動編集した内容は保持されます。

# from the open Figma file (plugin running), with @/ imports
npx figbridge-mcp call connect_components '{"fromPlugin": true, "imports": "{\"src/\":\"@/\"}"}'

3. 使用します。 Figma でインスタンスを選択し、プラグインの コード タブを開くと、Dev Mode のパネルのように、マッピングされたコンポーネント、現在の props、すぐに貼り付けられるスニペットが表示されます。エージェントは get_code_connect を呼び出します（nodeId、現在の選択、またはオフラインの node 説明を指定できます）。

// get_code_connect on a Button instance (Style=Secondary, Show icon, Icon=download, Label "Export 186")
import { Button } from '@/components/primitives/Button'
import { Download } from 'lucide-react'

<Button icon={Download} variant="secondary" size="m" testId={testId}>Export 186</Button>

4. 正確さを保ちます。 ソースファイル、エクスポート、prop がなくなった場合、マッピングされた値が prop のリテラル型ユニオンから外れた場合（別のモジュールからインポートされたユニオンや (typeof STATES)[number] を含みます）、またはマッピングされた Figma プロパティやバリアント値がエントリーの Figma スナップショットに存在しなくなった場合、lint_connect は失敗します。CI に追加します。

npx figbridge-mcp call lint_connect '{}'    # exit 1 when the map has rotted

シェルまたは CI からツールを呼び出す

すべてのツールは MCP クライアントなしで実行できます。

npx figbridge-mcp tools                                   # list tools
npx figbridge-mcp call map_components '{"sourceDir":"src"}'
npx figbridge-mcp call get_code_connect @args.json        # args from a file
echo '{"url":"http://localhost:5173"}' | npx figbridge-mcp call audit_mobile -

ツールの JSON を出力し、結果が ok: false の場合は終了コード 1 で終了します。Figbridge ブリッジ（Claude または figbridge-mcp bridge）がすでに実行中の場合、プラグインツールはそのブリッジを通じて、開いている Figma プラグインに接続します。

エージェントへの引き継ぎバンドル

get_agent_bundle が差別化要因です。1 回の呼び出しで zip を返します。

DESIGN.md          palette · rhythm · do/don't
hierarchy.md       indented tree with deterministic slugs
components.json    variants + props schema
tokens.json        DTCG-shaped
tokens.css         :root + per-mode blocks
flow.mmd           Figma prototype → Mermaid graph
responsive.md      mobile/tablet/desktop merged
ISSUES.md          a11y audit the agent shouldn't repeat
CHANGES.md         surgical diff since last bundle
AGENTS.md          "when you see slug X, import Y"
manifest.json      sha-256 + token counts, stable order for prompt cache
screenshots/       1:1 paired with hierarchy slugs

3 つのトークン上限（small 8k／medium 32k／large 128k）があります。スラッグは決定的です。ノード名を変更してもスラッグはそのままなので、CHANGES.md はファイル全体を再翻訳するのではなく、実際に変更された箇所だけを示す差分になります。

クローズドループ：URL → Figma → 差分 → パッチ

Figbridge は、双方向のクローズドループを実現する初の MCP ネイティブツールです。

                 import_url                      diff_to_source
   ┌──────────┐  ──────────▶  ┌──────────┐  ──────────▶  ┌──────────┐
   │  Source  │                │  Figma   │                │  changes │
   │  (URL,   │                │  frame   │                │   list   │
   │   repo)  │ ◀──────────    │ (edited) │                └────┬─────┘
   └──────────┘  generate_patch└──────────┘                     │
                                                                ▼
                                                         apply or review

1. import_url は、ライブ URL を Figma ページに取り込みます（pageName による複数ページの認識、rootSelector によるセクションの認識に対応しています）。
2. 5 つの Pillar 2 ツールで結果を監査し、パレットのずれ、コントラストの問題、グリッドから外れた余白、モバイル表示の崩れを検出します。audit_regression を使うと、本番環境／ステージング環境とローカルの候補を比較し、Figma の更新やコードのリリース前に UI／UX のリグレッションを検出できます。
3. デザイナーが Figma でフレームを編集します。
4. diff_to_source は、ソース URL から変更されたテキストノードのフィールド（文字列／fontSize／fontFamily／color／有無）を正確に報告します。
5. generate_patch は差分を、ローカルのソースディレクトリに対する最小限の変更前／変更後の編集リストに変換します。スタイルの切り替えには、無条件のテキスト置換ではなく、構造化されたヒント（トークンかリテラルか）が付与されます。

ループ内で LLM による書き換えはありません。すべてのステップは決定的で、べき等です。

出力形式

形式	内容
HTML + CSS	ピクセル単位の忠実度を保つ、位置指定レイアウトの自己完結型ドキュメントです。
Tailwind	同じツリー構造に Tailwind の任意値ユーティリティ（w-[120px]、bg-[#ff7a29]）と CDN スクリプトを追加します。
デザイントークン	DTCG JSON ツリー、:root { --var: value } CSS、Tailwind 設定の断片です。Figma Variables とローカルのペイントスタイルを読み取ります。

アーキテクチャ

• プラグインのメインスレッド（plugin/code.js） — ノードツリーを読み取り、HTML／CSS／Tailwind／トークンを決定的に計算します。Figma サンドボックスに対応するため、ES2017 セーフです（spread／??／?. は使用しません）。
• プラグイン UI（plugin/ui.html） — クリーム／インク／さび色のテーマ、Figma ネイティブのレイヤーナビゲーター、ツールごとに「Run」ボタンがあるインラインの「Commands」パネルを備えています。
• MCP サーバー（mcp/src/） — @modelcontextprotocol/sdk を使用する stdio MCP に加え、プラグインからのプッシュ送信と双方向コマンドに対応する、:7331 の HTTP + SSE サーバーを併設しています。状態はメモリ内に保持され、~/.figbridge/last.json にも保存されます。

Figbridge が行わないこと

• デスクトップアプリとプラグインを開いていない状態で Figma にアクセスすることはありません。REST API や PAT も使用しません。
• AI によるコードの書き換えはありません。決定的にツリーを走査します。
• Figma やクラウドへの公開は行いません。

開発

cd mcp && npm install && npm test        # integration smoke test
node test-agent/run.js                   # 130 unit tests on the render pipeline
node test/scenarios.mjs                  # 54 real-world scenario checks
node test/real-figma.mjs                 # 43 checks against a parsed real .fig
node test/tools-all.mjs                  # full MCP tool surface + e2e
node test/code-connect.mjs               # Code Connect: props reader, suggest, snippets, lint
node test/cli.mjs                        # figbridge-mcp call / tools
node --check plugin/code.js              # plugin syntax check

リンク

• ランディングページ：https://rudraptpsingh.github.io/figbridge/
• npm：https://www.npmjs.com/package/figbridge-mcp

ライセンス

MIT © Rudra Pratap Singh