Writable Figma MCP Bridge（Figma コネクタ）

あらゆる MCP 互換の AI クライアント に、Figma サンドボックス内で任意の JS を実行する汎用書き込みチャネルを提供します——ローカル、クラウドサービス不要、デフォルトでは本機のみアクセス可能。

標準 MCP で接続すれば、ほとんどのデスクトップ型 AI アシスタントで Figma ファイルの読み書きができます。

🌐 言語：日本語 ｜ English

一、はじめに

Figma コネクタは、ローカル MCP サービス + Figma プラグインの組み合わせで、任意のデスクトップ AI アシスタントが標準 MCP プロトコルを通じて編集中の Figma ファイルを読み書きできるようにするものです。全体の経路はあなたの本機上（127.0.0.1）で完結し、外部 API やクラウドサービスには依存しません。

設計理念は 「ローカル優先・監査可能」 です。全体の経路は自分のマシン上（127.0.0.1）だけで動作し、外部の API キーや OAuth に一切依存せず、コード量が小さく、完全に監査できます。

Related MCP server: Custom Figma MCP

二、主な特長

• 書き込み可能な MCP ブリッジ：figma_run_js を信頼できる書き込みエントリポイントとして MCP クライアントに公開します。

• 安全な書き込み：各タスクの実行前にノードをスナップショットし、エラー時には今回作成した新しいノードを自動ロールバックします。

• デザインシステム優先：helpers（デザインシステムのインデックス化、コンポーネントのインポート、変数へのバインド、スタイル適用など）を内蔵しており、ハードコードを回避します。

• 状態の可視化：パネルは「タスク待機中 / 読み取り中 / 書き込み中」の3状態をリアルタイム表示します（青=書き込み、緑=読み取り）。

• エイムボタン：各リンクからワンクリックでジャンプし、対象ノードを選択します（自動ズーム）。 ,

• リンク重複の通知：既存のリンクを貼り付けると、下部に「現在のリンクは既に存在します」というフローティング通知が表示され、誤操作を防ぎます。

• マルチプラグイン保護：GET /health がすべてのポーリングウィンドウを一覧表示し、FIGMA_WRITER_STRICT=1 で単一ウィンドウ専用を強制できるため、複数ウィンドウによる誤書き込みを防ぎます。

三、動作の仕組み

AI 客户端 (Claude / WorkBuddy)
        │  MCP (http://localhost:8788/mcp)
        ▼
本地 MCP 服务 (server.mjs)  ── 任务入队
        │
        ▲ 轮询 GET /plugin/job
        │
Figma 插件 (code.js 运行在 Figma 沙箱)  ── 在 Figma 内执行读/写
        │ 结果 POST /plugin/result
        ▼
本地 MCP 服务  ── 把结果回传给 AI

1. AI は MCP 経由でサービスエンドポイント（http://localhost:8788/mcp）を呼び出します。

2. サービス側はタスクをキューに追加します。

3. Figma プラグインが /plugin/job をポーリングしてタスクを取り出し、Figma 内で実行します（操作できるのは現在開いているファイルのみ）。

4. プラグインは POST /plugin/result で結果を AI に返信します。

⚠️ プラグインの実際の読み書き境界は「Figma が現在開いているドキュメント」です。パネルで選択されているリンクは「どのファイルを操作しているか」を明示し、サーバー/AI に報告するための識別子です。両者が一致しない場合でも、読み書きは現在開いているファイルが優先されます。

四、環境要求

• Node.js ≥ 18（ローカル MCP サービスの実行に必須。nodejs.org からダウンロードしてインストール）。

• Figma デスクトップ版（Web 版はローカルプラグイン/Dev モードをサポートしていません）。

• API Key 不要、OAuth 不要、ネットワーク不要（サービスは 127.0.0.1 のみで動作）。

五、クイックスタート

1. ローカルサービスの起動

方法 A：コマンドライン（推奨、ログ確認に便利）

cd writable-figma-mcp-bridge
node server.mjs

方法 B：ランチャーをダブルクリック

• macOS：リポジトリ内の start.command をダブルクリック

• Windows：start.bat をダブルクリック

スクリプトをダブルクリックすると、「最小化/バックグラウンド」で node server.mjs が起動し、コマンドを入力する必要はありません。前提として本機に Node.js がインストールされている必要があります。

起動後、デフォルトでは 127.0.0.1:8788 に公開され、本機からのみアクセス可能です。デフォルトで唯一のツール figma_run_js を公開します。

2. Figma にプラグインを手動インストール（重要）

Figma プラグインは、このリポジトリの manifest.json を手動でインポートする必要があります。手順は次のとおりです。

1. Figma デスクトップ版（公式サポートは macOS / Windows）を開きます。

2. 任意の Figma デザインファイルを開きます。

3. 上部メニュー：Plugins（プラグイン） → Development（開発） → Import plugin from manifest…（マニフェストからプラグインをインポート）。

4. ファイル選択ダイアログで、このリポジトリの manifest.json（writable-figma-mcp-bridge/manifest.json）を選択します。

5. メニュー Plugins（プラグイン） → Development（開発） → Writable Figma MCP Bridge を実行します。

6. 表示されたパネルの 「開始」 をクリックして、ローカルサービスに接続します。

「開始」が表示され、状態が「タスク待機中…」になればプラグインは接続されています。以降、AI が MCP 経由で送信する読み書きタスクはすべて、現在開いているこのファイルに対して実行されます。

3. MCP クライアントの設定

このサービスは常駐 HTTP サービスです。MCP 設定は Streamable HTTP エンドポイントを指す必要があります：

{
  "mcpServers": {
    "figma-writer": {
      "type": "http",
      "url": "http://localhost:8788/mcp"
    }
  }
}

上記の JSON を、お使いの MCP クライアント側の設定ファイルに書き込むだけで利用できます（具体的なパスはクライアントによって異なるため、それぞれの MCP 設定ドキュメントを参照してください）。

デフォルトポートは 8788 です。使用中の場合は、サービスは自動的に 8789、8790 … 以降のポート（最大50個まで）に切り替わり、起動ログに実際のアドレス（MCP endpoint: http://127.0.0.1:<実ポート>/mcp）が表示されます。ポートが変わった場合は、上記の設定のポートも実際のポートに変更してください。Figma プラグインのパネルはこれらのポートを自動検出するため手動設定は不要ですが、MCP クライアントは自動検出しないため、手動で同期する必要があります。

六、機能説明

リンク管理

• 上部の入力欄に Figma ファイルのリンクを貼り付け、「追加」をクリックすると下部のリストに追加できます。

• 各行は「選択」して現在のアクティブなリンクにできます（ポーリング時にサーバーへ報告）。また「エイム」ボタンが付いています。

• 重複するリンクを貼り付けた場合、下部に「現在のリンクは既に存在します」という赤いフローティング通知が表示されます。

エイムボタン（Aim）

各行のリンク右側にある十字の照準アイコンです。クリックするとリンク内の node-id が解析され、そのノードがあるページに切り替わって、自動的に中央へ連続して選択します。リンクが他のファイルを指している場合（現在開いているファイルからノードが見つからない場合）は、「リンクが他のファイルを指している可能性があります」と明確に提示します。

ステータス表示

パネル右上のステータスドットはタスクに応じて変化します。

• グレー「タスク待機中…」：アイドル状態

• ブルー「AI 書き込み中…」：書き込み操作を検出

• グリーン「AI 読み取り中…」：読み取り操作を検出

自動ロールバック

figma_run_js を実行するたびにドキュメントノードのスナップショットを取ります。実行中にエラーが発生した場合は、今回作成した新しいノードを自動的に削除し、ロールバック件数を報告します。既存ノードへの変更は自動ロールバックされません（Figma で Cmd/Ctrl+Z により取り消し可能です）。

七、セキュリティ

八、環境変数

九、利用可能な helpers（figma_run_js 内で利用可能）

figma_run_js には figma（Figma API）、args（構造化パラメータ）、helpers（安全なヘルパー群）が注入されます。

• helpers.loadFont(fontName)

• helpers.ensureTextFontLoaded(textNode, fallbackFontName)

• helpers.paint(value, theme) / helpers.hexToRgb(hex) / helpers.rgbToHex(rgb)

• helpers.normalizeHex(value, theme)

• helpers.findVariable(nameOrKey, resolvedType)

• helpers.indexDesignSystem(options)

• helpers.cloneReferenceNode(selector, options)

• helpers.importComponentByName(nameOrKey, options)

• helpers.applyTextStyle(textNode, styleName)

• helpers.applyPaintStyle(node, styleName, field)

• helpers.bindVariable(node, field, variableName, fallbackValue, resolvedType)

• helpers.bindFillVariable(node, variableName, fallbackValue) / helpers.bindStrokeVariable(...)

• helpers.findNodes(selector) / helpers.getNode(id)

• helpers.summarizeNode(node, depth) / helpers.inspectNodeAppearance(node)

• helpers.validateCanvas(options)

figma_run_js のコード内ではオプショナルチェーン ?. と null 結合演算子 ?? の使用を避けてください。Figma プラグインのランタイムが拒否する可能性があります。

十一、ライセンス

MIT License.