plumb-mcp

Plumb (plumb-mcp) — AI ネイティブなデザインエンジニアリングプラットフォーム

⭐ Plumb によってトークンを節約できたり、ページをデザインできたりしたら、GitHub でスターを付けて、ほかの人にも見つけてもらいましょう。

Plumb は、単一の MCP サーバーとして提供される、AI ネイティブなデザインエンジニアリングプラットフォームです。 Figma ファイル または 公開中のウェブサイトを指定すると、どちらも同じ セマンティックデザイングラフ に正規化します。重複を排除したトークン、Flexbox に基づいて解決したレイアウト、慎重に付与された役割ラベル（nav / hero / card …）をもとに、コーディングエージェントは実装でき、検証ループは評価できます。代わりに一行のプロンプトを指定すると、Plumb は AI デザインディレクター になります。最高水準の参考事例を調査し、ブランドを抽出し、キャンバス上にブランドに沿った Figma ファイル全体を生成したうえで、基準を満たすまで自らのレンダリングを批評します。

デザイン → コード（Figma または公開ウェブ、雰囲気ではなく検証済み）  •  プロンプト → デザイン（調査 → ブランド → 生成 → 批評）  •  その両方を支える単一のセマンティックデザイングラフ。 MCP ネイティブで、Claude Code、Cursor、Windsurf、または Model Context Protocol に対応するあらゆるエージェントで動作します。

📖 ドキュメント全文：https://tathagat22.github.io/plumb-mcp/  ·  📦 npm：plumb-mcp  ·  🇨🇳 简体中文  ·  🇯🇵 日本語  ·  🇰🇷 한국어

コーディングエージェント向けに構築されています。Claude Code、Cursor、Windsurf など、MCP 互換のあらゆるものに対応します。エージェントネイティブなデザインエンジニアリングを実現します。ダッシュボードも、面倒を見る別アプリも、Figma とエディターの間で人がピクセルをやり取りする作業も不要です。デスクトップアプリのプラグインを通じて Figma を読み取ります（REST のレート制限はなく、Free を含むすべてのプランで動作します）。ヘッドレス Chrome を通じてあらゆる公開ウェブサイトを読み取り、同じプラグインを通じて新しいデザインを Figma に 書き戻し ます。また、Figma API が出力する数十万トークンもの JSON ではなく、コンパクトで正規化された仕様を返します。

「Figmaコンバーター」ではなく「デザインエンジニアリングプラットフォーム」

ほとんどのFigma MCPサーバーや、一般的なFigmaからコードへの変換ツールは、入力も出力も一種類だけです。Figma JSONを入力し、あるフレームワークのコードを出力して終わりです。Plumbのアーキテクチャはパイプではなく、ハブです。

• 2つの独立したソースが同じグラフに取り込まれます。 plumb_node はFigmaの画面を正規化し、plumb_import_web はライブWebページのDOMを正規化します。どちらも、ピクセルの出所にかかわらず、プラットフォームに依存しない同じセマンティックグラフ（包含、繰り返しグループ、ロールのエッジ）に取り込まれます。
• すべてのコンシューマーは、どちらのソースに対しても変更なしで動作します。 plumb_emit_react は、グラフの出所がFigmaでもURLでも、同じ決定的なReact/JSXを生成します。plumb_diff、plumb_audit、plumb_query のロールフィルターも、どちらのソースに対しても同じように動作します。これこそが、2つ目の入力を後付けしたコンバーターではなく、プラットフォームであることの具体的な証明です。
• 検証は入力時だけでなく、出力時にもループを完結させます。 plumb_verify / plumb_fit は、出荷したコードを信頼できるソースと比較し、優先順位付きの修正案を返します。「見た目が合っている」を測定可能な事実に変えます。
• 生成はループを逆方向に回します。 plumb_studio は概要から新しいFigmaファイルを作成し、plumb_review は plumb_verify がコードを評価するのと同じ方法でレンダリングを評価します。

1つのセマンティックモデル。複数の入力ソース（Figma、Web）と、複数の出力先（Reactコード、Figmaファイル）。両端で検証します。それがこのプラットフォームです。

2つの方向、1つのサーバー

← FigmaまたはWeb → コード（読み取り方向）

エージェントは、画面、または plumb_import_web を使って取得した任意のライブURLを、同じセマンティックグラフに基づくコンパクトな Plumb Design Spec（PDS） として抽出します。オートレイアウトは事前にFlexboxへ変換され、デザイントークンは重複排除され、ロールにはラベルが付けられています。UIを構築した後、plumb_verify / plumb_fit を呼び出してレンダリング結果をソースと比較し、ピクセル単位で完全に一致するように自己修正します。コードとのループを完結させる唯一のFigma MCPであり、通常のWebページに対しても、Figmaファイルなしで同一のループを実行できる唯一のものです。

→ プロンプト → デザイン（書き込み方向 — デザインディレクター）

Plumbに「プレミアムなフィンテックダッシュボード」のような1行の概要を伝えると、Figma上でリアルタイムに作業するシニアデザイナーのように動作します。

1. 参考例を調査します — 概要に合う最高水準のサイト（Linear、Stripe、Mercuryなど）を見つけ、Referencesページにライブスクリーンショットを配置します。
2. ブランドを抽出します — それらのサイトの計算済みCSSを読み取り、一貫性のある配色と書体スケールにまとめ、Brandボードに配置します。
3. デザインを生成します — 高レベルのデザインDSLから、ブランドに沿った完全なページ（ナビゲーション、ヒーロー、機能、ギャラリー、CTA、フッター）を作成し、実際のFigmaノードとして構築します。
4. 自らのレンダリングを評価します — 呼び出し元のエージェント（Claude Code / ビジョン機能を備えた任意のMCPクライアント — MCPツールとして実行する場合は追加のAPIキー不要。例外はスタンドアロンの plumb-mcp fit CLIです。詳しくは以下のスタンドアロンCLIを参照してください）がスクリーンショットを評価します。Plumbはその結果を決定論的なデザイン基準と構造差分と組み合わせ、優先順位付きの修正リストを返し、基準を満たすまで反復します。

これは自己改善型のディレクターループを備えた、プロンプトからFigmaデザインを生成する仕組みであり、一度きりのモックアップではありません。

Plumbの違い

ご存じかもしれない、ほかのFigma MCPサーバー：

• Figmaの公式Dev Mode MCP — 双方向ですが、プランによる制限があり、利用量に応じて課金されます。
• Framelink — 薄いRESTラッパーです。ツールは2つ。検証機能はなく、レート制限も引き継ぎます。
• cursor-talk-to-figma — Figma 内で作業するデザイナー向けの双方向自動化ツールです。

さらにMCPの枠を超えた、デザインからコードへの変換／AI UI生成の広いカテゴリでは、html.to.design、Anima、Locofyといったツールや、v0、Builder.ioのVisual Copilotのようなプロンプト優先のジェネレーターが使われています。これらは通常、一方向にしか処理しません（デザインを入力してコードを出力する、またはプロンプトを入力してコードを出力する）。両方にまたがる共有モデルはなく、出力を後からソースと照合する組み込みステップもありません。

Plumbは、コードの検証ループを完結させると同時に、新しいデザインの生成を指示できる唯一のツールです。その基盤となるのは、ソースがFigmaでもURLでも変わらない1つのセマンティックグラフです。plumb_verifyを使うと、公開したコードがデザイン（または参照ページ）と実際に一致しているかを確認できます。plumb_fitを使えば、そこから自己修復ループを構築できます。plumb_import_webとplumb_emit_reactは、グラフが移植可能であることを証明します。同じロール分類器と同じコードジェネレーターが、Figmaをまったく使わずに実際のWebサイトを処理します。また、書き込み側では、plumb_studio／plumb_brand／plumb_design／plumb_reviewを使って、プロンプトからデザインを作成し、批評したうえでFigmaファイルに仕上げられます。デザインスキルも、別のデザインツールも、追加のモデルキーも必要ありません（MCPツールとして利用する場合。キーが必要な1つのコマンドについてはスタンドアロンCLIをご覧ください）。

次のようなエラーに困っていませんか？

エラーがきっかけでエージェントがここにたどり着いたのなら、Plumbで解決できる可能性があります。

インストール：npm install -g plumb-mcp → plumb-mcp init — またはAIエージェントにセットアップを任せる。

30 秒で動作を確認 — アカウントもキーもネットワークも不要です

インストールや Figma ファイルへの接続を行う前に、一連の処理を実行して自己採点する様子を確認しましょう。

npx plumb-mcp demo          # or: docker compose up demo

実際のデザイン仕様を用意し、同じ画面をビルドしたものに13 個の意図的なミスを仕込んで検証エンジンに渡します。たとえば、見出しの文字サイズが一段階小さい、ピル型ボタンが角丸の長方形として描画されている、グラデーションが単色で塗りつぶされている、バッジがまったく実装されていない、といったミスです。そして、検出結果を表示します。

  Round 1 · First pass — built straight from the spec, no verification
    ▰▰▰▰▰▰▰▱▱▱  71.0%   8 errors · 1 warnings · 32/34 key nodes built

    ✓ The "MOST POPULAR" badge was never built — no element carries its handle
      pro-badge           not built         no data-plumb-id for this handle in the DOM
    ✓ Headline came out one step down the type scale (48px → 40px)
      title               text.size         expected 48  ·  got 40
    ✓ Primary CTA is a hand-picked purple, not the brand token
      pro-cta             fill              expected #6366f1  ·  got #7c5cf5
    …

  Scoreboard
    Mistakes planted      13
    Caught                13   (100% recall)
    False positives       0   across 27 untouched nodes
    Convergence           71.0% → 96.2% → 100.0%

Figma トークンも、プラグインも、ブラウザーも、ネットワークも不要です。docker compose up demo は network_mode: none でも実行できます。デモを採点するエンジンは、plumb_verify と plumb_fit の背後で動くものと同じです。また、その数値は src/demo/demo.test.ts でアサートされているため、結果が正しくなくなるとデモは CI で失敗します。plumb-mcp demo --pds を実行すると、基準となるデザイン仕様が表示されます。--json を指定すると、スクリプトで使える形式で結果を出力し、エンジンが見落とした項目がある場合は 0 以外の終了コードを返します。

AI エージェントにセットアップを任せる

Plumb を使いたいプロジェクトの中で、Claude Code、Cursor、Windsurf、またはシェルを使えるコーディングエージェントに、以下を貼り付けてください。インストールと設定はエージェントが行います。エディターの再起動と、Figma での Pair のクリックという、あなたにしかできない 2 つの手順では停止し、案内します。

Set up Plumb (https://github.com/tathagat22/plumb-mcp), the Figma MCP server, for
this project. Follow these steps in order and tell me what you did at each one.

1. Check prerequisites: Node 20+ (`node -v`) and npm. If Node is older than 20,
   stop and tell me how to upgrade. Don't upgrade it yourself.
2. Install: `npm install -g plumb-mcp`, then confirm it with `plumb-mcp --version`.
   If the global install fails with a permissions error, tell me and don't use sudo.
3. Smoke test: run `plumb-mcp demo`. It works offline and needs no Figma account.
   Its scoreboard should show "Caught 13 (100% recall)". If it doesn't, stop and
   show me the output.
4. Wire up the editor: run `plumb-mcp init` from this project's root. It detects
   Claude Code / Cursor / VS Code / Windsurf and writes the MCP config (for Claude
   Code that's `.mcp.json` here). It also adds those files to .gitignore. Show me
   which files it wrote and the Figma plugin manifest path it printed.
   - Leave the FIGMA_TOKEN placeholder alone unless I give you a token. The plugin
     path doesn't need one. Never commit a real token.
5. Hand off to me. Tell me exactly:
   a. Restart the editor / agent session so it loads the Plumb MCP server.
   b. Open the Figma DESKTOP app (the browser version can't sideload plugins) →
      Plugins → Development → Import plugin from manifest… → pick the manifest
      path from step 4.
   c. Open my design file, run the Plumb plugin, and click "Pair with Plumb".
6. After I restart and pair, call the `plumb_status` tool. Success means
   `connected: true` with a screen count. Then call `plumb_outline` and list my
   screens. If it isn't connected, follow the `note` field in the plumb_status
   response and try again.

Don't change any other files in this project during setup.

plumb_status で接続が確認できたら、実際の作業を依頼してみましょう。例：「Plumb で Settings 画面を抽出してビルドし、一致するまで plumb_fit を実行してください。」

クイックスタート

# 1. Install
npm install -g plumb-mcp

# 2. Wire into your editor — auto-detects Claude Code / Cursor / VS Code / Windsurf
plumb-mcp init

# 3. Sideload the Figma plugin (one-time). Find the manifest:
echo "$(npm root -g)/plumb-mcp/figma-plugin/manifest.json"
#    Figma desktop → Plugins → Development → Import plugin from manifest…
#    Run Plumb → click "Pair with Plumb" → done. Future runs collapse to a dot.

次に、エージェントで以下を実行します。

# Figma → code
"Extract the Settings screen with Plumb and build it, then plumb_fit until it matches."

# web → code, no Figma required
"Use plumb_import_web on https://example.com, then plumb_emit_react to scaffold it."

# prompt → design
"Use plumb_studio to design a premium fintech dashboard, then screenshot it and
 run plumb_review as the director until the score clears 90."

その他のインストール方法：npx plumb-mcp · docker run --rm -i ghcr.io/tathagat22/plumb-mcp:latest。

git clone https://github.com/tathagat22/plumb-mcp
cd plumb-mcp
npm ci
npm run demo        # the offline walkthrough — proves the checkout works
npm test            # 600+ specs
npm run typecheck   # strict TS, server + plugin
npm run lint
npm run build       # bundles the server, the Figma plugin, and Studio into dist/
node dist/index.js --help

28 個のツール、1 つのセマンティックグラフ

以下のすべてのツールは、前述の同じセマンティックデザイングラフから読み取るか、そこに書き込みます。これにより、新しいソース（Web）や新しいターゲット（React）を追加しても、書き換えではなく拡張で対応できます。

読み取り — Figma または Web → コード

書き込み — プロンプト → デザイン（ディレクター）

トークン効率と品質に優れている理由

• コンパクトな仕様。 351k トークンの Figma REST JSON になる 178 ノードのダイアログが、重複を除いたトークン、Flexbox で解決されたレイアウト、深さに左右されないハンドルを備えた PDS では約 2.6k トークンになります。
• 感覚ではなく、検証します。 plumb_verify / plumb_fit は、デザインとレンダリング結果を比較します（ΔE2000 の知覚色、シャドウ、回転、Flex の子要素、塗りのスタック）。ピクセル差分ではなく、CI で実行できます。
• デフォルト任せではなく、設計します。 書き込み方向には、サイズを考慮した文字間隔、ゆとりのあるセクションのリズム、実際のリファレンスから抽出したブランドパレット、グラデーションテキスト、全幅および非対称のレイアウト、レンダリングを評価して改善するビジョンベースのディレクターなど、本格的なデザイン技術が組み込まれています。
• 構造も理解します。ジオメトリだけでも、Figma だけでもありません。 Plumb は、生のツリーに対して nav/hero/footer/sidebar/card を控えめにタグ付けします（node.pattern — シグナルが一致しない場合は推測せず、何も示しません）。そして、その情報を基に機能を構築します。plumb_diff は役割ごとに変更を説明し、plumb_audit はコントラストとタッチターゲットの問題を検出します。また、plumb_query の select: "role" と plumb_node の collapseRoles は、同じラベルでフィルタリングと圧縮を行います。同じ基盤モデルは、ライブ Web ページも読み取れます。plumb_import_web は Figma を介さず、任意の URL から構造と役割を抽出し、plumb_emit_react はどちらのソースからも決定論的な React/JSX を生成します。

2 つのデータ経路

ツールは経路を自動選択します。プラグインを連携している場合は、fileKey を省略し、id または name を渡してください。

設定

Plumb を試すために設定は不要です。npm run demo は設定なしで実行でき、プラグイン経路（plumb_outline、plumb_node、plumb_selection、…）に必要なのは Figma プラグインとの連携だけです。

ローカルで使用する場合は、.env.example を .env（gitignore 対象）にコピーしてください。Plumb は起動時に作業ディレクトリとパッケージのルートから読み込みます。ただし、MCP クライアントはサーバーを新しいプロセスとして起動するため、キーを設定する場所として最も確実なのは、クライアントのサーバー env ブロックです。

環境変数

コンテナーで実行する

docker compose up demo      # the offline walkthrough, network disabled — start here
docker compose up bridge    # bridge + Plumb Studio on http://127.0.0.1:31337
docker compose run --rm mcp # the stdio MCP server, for an editor to attach to

ブリッジは GET /healthz（/health のエイリアス）を提供します。これは稼働状態と、プラグインが実際にペアリングされているかどうかを示し、Compose のヘルスチェックが確認します。また、Prometheus のテキスト形式で GET /metrics も提供します。

bridge は固定ポートを1つ公開します（コンテナーでは公開するポートを事前に指定する必要があるため、ポートのスキャンは行わず、PLUMB_BRIDGE_PORT を使用します）。そのポートはホストのループバックのみにマッピングされるため、ネイティブで実行する場合よりもアクセス範囲が広がることはありません。エクスポートしたアセット、スクリーンショット、キャッシュは plumb-data ボリュームに保存されます。

devcontainer も用意されています。VS Code または Codespaces でリポジトリを開くと、両方のワークスペースがインストールされ、アタッチ時にデモが実行されます。

Kubernetes で実行 — 定期的にデザインの乖離を検出

helm install plumb ./deploy/helm/plumb --namespace plumb --create-namespace
helm test plumb --namespace plumb
kubectl -n plumb port-forward svc/plumb 31337:31337   # Studio + plugin pairing

Helm チャート、プレーンマニフェスト、Terraform モジュールのいずれを使っても、同じ制限付きデプロイを実現できます。すべて CI で検証されます（helm lint、2 つの Kubernetes バージョンの実際の API スキーマに対する kubeconform -strict、terraform validate、Trivy と Checkov によるポリシースキャン、さらにプレーンマニフェストがチャートから乖離しないよう再生成して差分を確認します）。

Plumb をノートパソコンだけでなくクラスターで実行する理由は、継続的なデザイン検証です。CronJob がすでに配信している URL をレンダリングし、すべての [data-plumb-id] 要素を、その要素の作成元である Figma ノードと比較して差分を確認し、乖離があれば失敗します。

verify:
  enabled: true
  schedule: "0 * * * *"
  targets:
    - name: dashboard
      url: http://app.default.svc.cluster.local/dashboard
      node: "190:109884"

デザインのリグレッションは、3 週間後のレビューで誰かが気づくものではなく、タイムスタンプと差分一覧を伴う失敗ジョブになります。

ブリッジには独自の認証機能がありません。セキュリティモデルはループバック接続と、意図的なペアリング操作で成り立っています。そのため、デフォルトでは何も公開しません。ClusterIP、すべてを拒否する NetworkPolicy、Ingress なし、接続方法は kubectl port-forward です。deploy/README.md には、クラスターでできること、できないこと（Figma プラグインは 127.0.0.1 をスキャンするため、ポートフォワードが必要です）、各スイッチで実際に何が公開されるかが明記されています。

スタンドアロン CLI

2 つのコマンドは、MCP クライアントを介さず、ターミナルから直接実行できます。CI や、エージェントを介さずに Plumb を操作する場合に便利です。

plumb-mcp verify <dev-url> --node <figma-node-id>   # diff a running page against the design
plumb-mcp fit <figma-url>                           # generate + self-correct an HTML build until it matches

plumb-mcp verify に必要なのは FIGMA_TOKEN だけです（ペアリング済みの場合はプラグインを利用できます）。差分を確認するだけで生成はしないため、モデルのキーは不要です。plumb-mcp fit は、このプロジェクト全体で外部モデルを直接呼び出す唯一のコマンドです。HTML ビルド自体を生成する（その作業を行うエージェントがいない）ため、FIGMA_TOKEN に加えて ANTHROPIC_API_KEY が必要です。plumb_fit や plumb_review を含むすべての MCP ツールは、呼び出し元のエージェントが生成や判断を行うため、キーは不要です。

ネットワークの送信先

上記の通信が勝手に発生することはありません。すべてのネットワーク呼び出しは、実行したツールまたは CLI コマンドに直接起因します。バックグラウンドでのポーリング、テレメトリ、外部への自動通信はありません。

セキュリティ

• ループバック専用の WebSocket ブリッジ。ペアリングできるプラグインは同時に 1 つのみです（意図的なクリックが 1 回必要です）。
• テレメトリはありません。プラグイン経由の場合、個人用アクセストークンは不要です。
• 書き込み方向では外部モデルを呼び出しません。すでに MCP サーバーを操作している AI エージェントがデザインの判断を行います（例外はスタンドアロンの plumb-mcp fit CLI のみです。スタンドアロン CLIを参照）。

貢献

誤字の修正から、新しい検証チェックの追加、デザインディレクターのアップグレードまで、あらゆる貢献を歓迎します。詳しくはCONTRIBUTING.mdをご覧ください。初めての方は、good first issueラベルをご覧ください。

ライセンス

MIT © Tathagat Maitray。詳細はLICENSEをご覧ください。