Figma Vector MCP

Figma Vector MCP

Figma のプラグインと MCP サーバーを組み合わせ、ローカルの WebSocket リレーを介して、Claude（または任意の MCP クライアント）が Figma キャンバス上に、パス、図形、グラデーション、テキスト、エフェクト、画像塗りつぶしなど、完全に編集可能なベクターノードを作成・操作できるようにします。

Working Model Inc が開発しました。

バージョン 0.3.3 — 作成、スタイル設定、レイアウト、コンポーネント、エフェクト、ページ、エクスポートに対応した 58 個のツール。

このツールを作った理由

cursor-talk-to-figma-mcp は、Figma の状態を読み取ったり基本的なプリミティブを作成したりするのに優れていますが、ベクターパスの作成、グラデーション、エフェクト、合成のツールはありません。このプラグインはその不足を補います。

機能	cursor-talk-to-figma-mcp	figma-vector-mcp
長方形／楕円／フレーム／テキストを作成	✅	✅
SVG 文字列から作成	❌	✅
パスの d 文字列から作成	❌	✅
ポリライン／ポリゴンを作成	❌	✅
グラデーション塗りつぶし（線形、放射状、角度、ひし形）	❌	✅
画像塗りつぶし（base64 → キャンバス）	❌	✅
エフェクト（シャドウ、ぼかし）	❌	✅
ブレンドモード	❌	✅
ブーリアン演算（結合、減算など）	❌	✅
オートレイアウト	❌	✅
コンポーネントとインスタンス	❌	✅
フォントの検索	❌	✅
ノードの検索	❌	✅
複数ページの管理	❌	✅
名前付きノードレジストリ	❌	✅
バッチコマンド（1 回の往復で実行）	❌	✅
自動再接続とコマンドキュー	❌	✅
SVG と PNG のエクスポート	❌	✅

---

アーキテクチャ

Claude (MCP client)
  ↕ stdio (MCP protocol)
server.ts (MCP server)
  ↕ WebSocket (ws://localhost:3055)
socket.ts (relay — channel-based routing)
  ↕ WebSocket
Figma plugin (ui.html ↔ code.js)
  ↕ postMessage
Figma Plugin API → canvas

ソケットリレーはローカルで動作します。Figma プラグインが接続して、名前付きチャンネルに参加します。MCP サーバーも同じチャンネルに参加し、コマンドを送信します。結果は同じ経路を通って返されます。

---

AI エージェント向けクイックスタート

AI エージェント（Claude Code、Cursor など）向け — セッションを開始する際に推奨される呼び出し手順です。

1. health_check                    → confirm plugin is connected
2. get_document_info               → get page IDs, current page, top-level nodes
3. get_available_fonts             → discover loadable fonts before create_text
4. get_styles                      → load brand colours/text styles if available

色の規則： すべての RGB 値は、全体を通して 0～1 です（Figma の内部形式に準拠）。r: 1, g: 0, b: 0 は赤です。0～255 は使用しないでください。

グラデーションのワークフロー：

1. create_frame({ width, height })          → get frameId
2. set_gradient_fill({ nodeId: frameId, type: "LINEAR", angle: 135,
     stops: [{ color: { r:0.2, g:0.1, b:0.9 }, position: 0 },
             { color: { r:0.9, g:0.2, b:0.4 }, position: 1 }] })

画像塗りつぶしのワークフロー（生成 AI を使用）：

1. Generate image via Replicate/fal.ai → get base64 PNG
2. create_frame({ width: 512, height: 512 })
3. set_image_fill({ nodeId, base64, scaleMode: "FILL" })

バッチ合成 — $prev.id を使うと、余分な往復なしでコマンドを連結できます。

{ "commands": [
    { "command": "create_frame", "params": { "width": 400, "height": 300, "name": "Card" } },
    { "command": "set_gradient_fill", "params": { "nodeId": "$prev.id", "type": "LINEAR",
        "stops": [{"color":{"r":0.1,"g":0.1,"b":0.9},"position":0},
                  {"color":{"r":0.8,"g":0.2,"b":0.5},"position":1}] } },
    { "command": "create_text", "params": { "parentId": "$results.0.id",
        "text": "Hello", "fontSize": 32, "x": 24, "y": 24 } }
]}

既知の SVG の制限： figma.createNodeFromSvg() は <defs>、グラデーション、フィルター、マスク、アニメーションを削除します。SVG の <linearGradient> の代わりに、グラデーションには set_gradient_fill を使用してください。

再接続： プラグインが切断されると、指数バックオフ（1 秒から最大 30 秒）で自動再接続し、キューに入ったコマンド（最大 30 秒前まで）を再送します。短時間の切断であれば手動での対応は不要です。

---

セットアップ

1 — プラグインをインストールする

1. このリポジトリをクローンするか、ソースをダウンロードします
2. Figma デスクトップアプリで、Plugins → Development → Import plugin from manifest を選択します
3. src/figma-plugin/manifest.json を選択します

2 — MCP サーバーをインストールする

npm install -g figma-vector-mcp
# or use without installing via npx / bunx (see MCP config below)

3 — ソケットリレーを起動する

bun run socket

ws://localhost:3055 で待ち受けます。ログイン時に自動起動する（macOS）：

./scripts/setup.sh --launchd

4 — MCP サーバーを設定する

# Auto-detect Claude Code / Cursor and write config:
./scripts/setup.sh

# Local build:
./scripts/setup.sh --local

# Install git pre-commit sandbox lint hook:
./scripts/setup.sh --hooks

手動設定（~/.claude/settings.json または ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "FigmaVectorMCP": {
      "command": "bunx",
      "args": ["figma-vector-mcp@latest"],
      "env": { "FVMCP_CHANNEL": "figma-vector-mcp" }
    }
  }
}

5 — プラグインを接続する

1. Figma ファイルを開きます
2. Plugins → Development → Figma Vector MCP を選択します
3. サーバー URL（ws://localhost:3055）を入力し、Connect を選択します
4. チャンネル名（figma-vector-mcp）を入力し、Join を選択します

プラグインは最後に使用した URL とチャンネルを保存するため、次回開いたときに入力済みの状態になります。セッション中はプラグインパネルを開いたままにしてください。閉じると WebSocket 接続が終了します。

6 — 動作を確認する

health_check → { "status": "ok", "version": "0.3.3", "currentPage": { ... } }

---

環境変数

変数	デフォルト	説明
FVMCP_PORT	3055	ソケットリレーのポート
FVMCP_CHANNEL	figma-vector-mcp	チャネル名 — プラグインと一致させる必要があります
FVMCP_TIMEOUT_MS	10000	デフォルトのコマンドタイムアウト（ms）

ツールごとのタイムアウト設定：health_check → 3s、export_node_as_png → 30s、export_node_as_svg → 15s、create_batch → 60s。

---

ツールリファレンス

接続とヘルスチェック

ツール	説明	主なパラメーター
health_check	プラグインに ping を送信し、接続を確認します	—
join_channel	名前付きチャネルに参加します	channel

ベクターの作成

ツール	説明	主なパラメーター
create_vector_from_svg	SVG 文字列から編集可能なベクターを配置します	svg, x, y, name, parentId
create_path	SVG の d パス文字列からベクターを作成します	d, x, y, fillColor, strokeColor, strokeWeight
create_polyline	[x,y][] の点のペアからベクターを作成します	points, closed, strokeColor, strokeWeight

プリミティブ

ツール	説明	主なパラメーター
create_frame	コンテナーフレーム	width, height, x, y, fillColor
create_rectangle	長方形	width, height, x, y, fillColor
create_ellipse	楕円／円	width, height, x, y, fillColor
create_text	オプションで固定幅の列を指定できるテキストノード	text, fontSize, fontFamily, fontStyle, fillColor, width, height, textAutoResize

塗りと色

ツール	説明	主なパラメーター
set_fill_color	単色の RGBA 塗り（0–1）	nodeId, r, g, b, a
set_gradient_fill	グラデーション塗り — LINEAR、RADIAL、ANGULAR、DIAMOND	nodeId, type, stops, angle, center, gradientTransform
set_image_fill	Base64 画像を塗りとして設定します	nodeId, base64, scaleMode, opacity

ストローク

ツール	説明	主なパラメーター
set_stroke	ストロークを詳細に設定します	nodeId, color, weight, position, dashPattern, lineCap, lineJoin
set_stroke_color	ストロークの色と太さを手早く設定します	nodeId, r, g, b, a, weight

エフェクトと合成

ツール	説明	主なパラメーター
set_effect	ドロップシャドウ、内側のシャドウ、ぼかし、背景のぼかし	nodeId, effects[] (type, color, offset, blur, spread), mode (REPLACE | APPEND)
set_blend_mode	レイヤーのブレンドモード	nodeId, mode (NORMAL, MULTIPLY, SCREEN, OVERLAY…)

ノードの操作

ツール	説明	主なパラメーター
set_corner_radius	角丸 — 全角共通または角ごとに指定	nodeId, radius or topLeft, topRight, bottomLeft, bottomRight
set_opacity	不透明度 0–1	nodeId, opacity
set_text_style	テキストのプロパティとテキストボックスのサイズを変更します	nodeId, fontSize, fontFamily, fontStyle, letterSpacing, lineHeight, textAlign, fillColor, width, height, textAutoResize
rename_node	ノード名を変更します	nodeId, name
set_visibility	ノードの表示／非表示を切り替えます	nodeId, visible
reorder_node	親内での Z 順を変更します	nodeId, action (BRING_TO_FRONT / SEND_TO_BACK / BRING_FORWARD / SEND_BACKWARD) or index
move_node	位置を変更します	nodeId, x, y
resize_node	サイズを変更します	nodeId, width, height
delete_node	キャンバスから削除します	nodeId
clone_node	複製し、必要に応じて位置を変更します	nodeId, x, y, parentId
group_nodes	ノードをグループ化します	nodeIds[], name, parentId
ungroup_nodes	グループ化を解除します	nodeId
boolean_operation	結合、減算、交差、除外	nodeIds[], operation, name
create_mask	クリッピングマスク — maskNode で targetNode をクリップします	maskNodeId, targetNodeId, name

レイアウト

ツール	説明	主なパラメーター
set_auto_layout	自動レイアウトを有効化／設定	nodeId、direction、spacing、padding、primaryAxisAlign、counterAxisAlign、primaryAxisSizingMode、counterAxisSizingMode、wrap
set_layout_grid	フレームに列／行／グリッドのガイドを設定	nodeId、grids[]（pattern、count、gutterSize、sectionSize、alignment、color）
batch_set_properties	塗り／線／不透明度／位置／サイズを一括更新	operations[]（nodeId と任意のプロパティの組み合わせ）

コンポーネント

ツール	説明	主なパラメーター
create_component	フレーム／グループをコンポーネントに変換	nodeId、name
create_instance	コンポーネントのインスタンスを配置	componentId、x、y、parentId
get_components	すべてのローカルコンポーネントを一覧表示	—
get_library_components	名前でローカルコンポーネントを検索	query

ドキュメントとページ

ツール	説明	主なパラメーター
get_document_info	ドキュメント名、ページ、現在のページの子要素	—
get_selection	現在選択されているノード	—
get_node_info	塗り、線、レイアウト、テキスト、制約など、ノードの詳細情報	nodeId
set_focus	ビューポートをノードまでスクロールして選択	nodeId
find_nodes	名前やタイプで検索	query、type、pageId、recursive
get_page_list	すべてのページ	—
switch_page	ページをアクティブ化	pageId または pageName
create_page	新しいページを作成	name
duplicate_frame_to_page	ノードを別のページにコピー	nodeId、targetPageId、x、y

ノードレジストリ

ツール	説明	主なパラメーター
register_node	ノード ID に名前付きエイリアスを保存（ドキュメントに保持）	alias、nodeId
resolve_node	エイリアスからノード ID を検索	alias

カラーレジストリ

ツール	説明	主なパラメーター
register_color	名前付きカラーをドキュメントのパレットに保存（0～1）	alias、r、g、b、a
resolve_color	エイリアスからカラーを検索	alias
list_colors	ドキュメントに登録されたすべてのカラーを一覧表示	—

スタイルとフォント

ツール	説明	主なパラメーター
get_styles	すべてのローカルのペイントスタイルとテキストスタイル	—
apply_style	ドキュメントのスタイルをノードに適用	nodeId、styleId、styleType
get_available_fonts	読み込み可能なフォントを一覧表示。名前で絞り込み	query

エクスポート

ツール	説明	主なパラメーター
export_node_as_svg	ノードを SVG 文字列としてエクスポート	nodeId
export_node_as_png	base64 PNG としてエクスポート	nodeId、scale（デフォルトは 2）
screenshot_current_page	ページ全体を base64 PNG としてエクスポート	scale

バッチ

ツール	説明	主なパラメーター
create_batch	複数のコマンドを 1 回のラウンドトリップで実行します。連鎖には $prev.id と $results.N.field のトークンを使用できます。	commands[]（command、params）

---

サンドボックスとの互換性

プラグインのメインスレッド（code.js）は、Figma の制限付き QuickJS サンドボックスで実行されます。UI（ui.html）は通常のブラウザーコンテキストであり、影響を受けません。

ビルド前に bun run lint:plugin を実行して、code.src.js に違反がないか確認してください。./scripts/install-hooks.sh を使用して、コミット前フックをインストールできます。

code.js で禁止されているもの

API / 構文	安全な代替手段
import / export	依存関係をすべてインライン化する
x ?? y	(x != null) ? x : y
obj?.prop	obj && obj.prop
{ ...obj } / [ ...arr ]	Object.assign({}, obj) / Array.from(arr)
localStorage	figma.clientStorage
TextDecoder	String.fromCharCode をチャンク単位で使用する
fetch()	メインスレッドでは使用できません
figma.getNodeById()（同期）	await figma.getNodeByIdAsync()
figma.currentPage = x（同期代入）	await figma.setCurrentPageAsync(x)
figma.getLocalPaintStyles()（同期）	await figma.getLocalPaintStylesAsync()
figma.getLocalTextStyles()（同期）	await figma.getLocalTextStylesAsync()
ページを読み込まずに figma.root.findAllWithCriteria() を呼び出す	先に await figma.loadAllPagesAsync() を実行する

SVG の互換性（create_vector_from_svg）

機能	状態
<rect>、<polygon>、<polyline>、<path>、<circle>、<ellipse>	✅
fill、stroke、stroke-width、stroke-linecap、stroke-linejoin	✅
viewBox、width、height	✅
<defs> 内の <linearGradient> / <radialGradient>	❌ 削除されます — set_gradient_fill を使用してください
<filter>、<mask>、<pattern>	❌ 削除されます
<animate>、<animateTransform>	❌ 削除されます
<script>、<foreignObject>	❌ 削除されます
fill="url(#...)" 参照	❌ fill="none" に置き換えられます

---

開発

bun install              # install deps
bun run socket           # start relay on :3055
bun run build            # build MCP server → dist/server.js
bun run build:plugin     # build plugin: code.src.js → code.js
bun run lint:plugin      # check code.src.js for sandbox violations
./scripts/install-hooks.sh  # install pre-commit lint hook

プラグインのワークフロー

1. src/figma-plugin/code.src.js を編集します
2. bun run lint:plugin — ビルド前にサンドボックスの違反を検出します
3. bun run build:plugin — esbuild により code.js（ES2017）が出力されます
4. Figma でプラグインパネルを閉じて再度開き、新しい code.js を読み込みます

---

クレジット

• ソケットリレー（src/socket.ts）は cursor-talk-to-figma-mcp を基に改変 — Copyright (c) 2025 sonnylazuardi、MIT License
• code.src.js の setCharacters ヘルパーは同じプロジェクトを基に改変 — Copyright (c) 2025 sonnylazuardi、MIT License

---

ライセンス

MIT © Working Model — LICENSE および THIRD_PARTY_NOTICES.md をご覧ください。

---

Working Model Inc が開発