use_figmaとは？Figma MCPでキャンバスに書き込む使い方・制限・上限

use_figmaは、Figma MCPサーバーの書き込み用ツールです。AIエージェントが書いたJavaScriptを、FigmaファイルのなかでPlugin API経由で実行し、フレーム・コンポーネント・変数・Auto Layoutを編集できるFigmaのデータとして作ります。公開後に公式の記述が何度も変わり、「Devシートは書き込めない」「カスタムフォントは使えない」といった夏までの説明は10月時点では当てはまりません。2026年10月23日時点の公式ドキュメントと公式スキルをもとに、使う条件、スクリプトの書き方、制限と上限を整理します。

まとめ：use_figmaの要点（2026年10月時点）

• use_figmaは、Plugin APIのJavaScriptをファイル内で実行する汎用の書き込みツールです。対象はFigma Design・FigJam・Figma Slides・Figma Specsの4種類です。
• リモートサーバー（https://mcp.figma.com/mcp）専用です。対象プランはProfessional・Education・Organization・Enterpriseで、下書き以外のファイルに書くにはFullシートと編集権限が要ります。Devシートは自分の下書きにだけ書けます。
• 書き込み対応のクライアントは公式表で22種です。呼び出しの前に公式スキル figma-use を読み込ませます。
• 応答は1回20KBまでです。新しい画像は upload_assets か generate_image で入れ、フォントはFigmaアカウントにアップロードしたものだけが使えます。
• ベータ期間中は無料で、将来は従量課金になると公式が明記しています。書き込み系ツールはレート上限の対象外とされていますが、対象外の列挙にuse_figmaの名前はありません。

use_figmaの仕組み：Plugin APIによるファイル内でのJavaScript実行

2026年3月24日の公開と書き込みツールの役割分担

Figmaは2026年3月24日の公式ブログ「Agents, meet the Figma canvas」で、AIエージェントがキャンバスに直接デザインする機能を公開しました。その実体がuse_figmaです。10月時点のツール一覧には書き込み系が14種あり、デザインを作るツールは次のように役割が分かれています。

既存のコンポーネントや変数を使って組めるのはuse_figmaだけです。稼働中の画面を generate_figma_design で取り込み、use_figmaで社内のコンポーネントに置き換える併用が公式の想定です。サーバー全体のツール構成と接続手順はFigma MCPサーバーの料金と上限｜無料枠・プラン別の呼び出し回数・接続手順にまとめています。

戻り値だけがエージェントに返る実行モデル

use_figmaに渡すのは、トップレベルで await と return が使える素のJavaScriptです。コードは自動で非同期関数に包まれるので、自分で (async () => { ... })() に包んだり figma.closePlugin() を呼んだりしてはいけません。

エージェントが受け取れるのは、return した値と投げられた例外だけです。console.log() の出力は返りません。呼び出しをまたいで状態は残らず、ページも毎回先頭に戻るので、作成・変更したノードのIDは return で返し、次の呼び出しに文字列で渡します。公式スキル figma-use は、利用できる環境では最初に create_session を呼び、返った sessionId をその後の呼び出しへ渡すよう指示しています。ただし create_session は開発者ドキュメントのツール一覧には載っていません。

Figma Design・FigJam・Slides・Specsで作れるノード

use_figmaは4種類のファイルで動きますが、作れるノードは種類ごとに違います。ファイルの種類はURLで見分けます。figma.com/design/ ならDesign、figma.com/board/ ならFigJam、figma.com/slides/ ならSlidesです。

figma.createPage() を使えるのはDesignだけで、FigJamとSlidesでは TypeError で止まります。Slidesには専用の読み取りツールがまだ無いため、中身を調べるときも読み取りだけのスクリプトをuse_figmaで実行します。Figma Specsはオープンベータで、Specsが有効なプランでだけ使えます。要件をSpecsから読ませて組ませ、決まったことを書き戻させるのが公式の使い方です。

use_figmaを使う条件：プラン・シート・リモートサーバー・対応クライアント

Full・Devシートの書き込み範囲と対象プラン

write to canvasのページが挙げる対象は、Professional・Education・Organization・Enterpriseの各プランです。Starterプランは入っていません。既存のファイルを変えるには、そのファイルの編集権限も要ります。

シートの条件は、2026年10月19日更新のFigma MCP server FAQsが書いています。下書き以外のファイルに書くにはFullシートが必要です。Devシートでも自分の下書きには書け、ほかのファイルはデザインのコンテキスト・スクリーンショット・メタデータ・変数を読む用途に限られます。9月までの公式の書き方は「Devシートは読み取りのみ」でした。認証中のアカウントとシートは、エージェントに whoami を実行させると、メールアドレス・所属プラン・プランごとのシートが返ります。

リモートサーバー専用と書き込み対応の22クライアント

use_figmaはツール一覧で「Remote only」です。Figmaデスクトップアプリ内で動くデスクトップ版のMCPサーバーでは使えません。2026年10月22日更新のGuide to the Figma MCP serverのクライアント表では、27種のうち22種に書き込みの印があります。

• 書き込みの印がある：Amp、Augment Code、Claude Code、Claude Desktop、ClickUp、Codex、Copilot CLI、Cursor、Dia、Factory、Firebender、Junie、Kiro、Linear、Meta Muse、Mistral、Notion、OpenCode、Sarvam Agents、VS Code、Warp、Xcode（ベータ）

Claude Code・Cursor・VS Code・Copilot CLI・Xcodeは、MCPの設定と公式スキルをまとめたFigmaプラグインを入れるのが公式の推奨です。コマンドはリモートサーバーの導入ページのものです。

# Claude Code：プラグインでMCP設定と公式スキルを同時に入れる
claude plugin install figma@claude-plugins-official

# Claude Code：MCPサーバーだけを全プロジェクト共通で追加する場合
claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

# Codex CLI：MCPサーバーだけを追加する場合
codex mcp add figma --url https://mcp.figma.com/mcp

Cursorではエージェントのチャットで /add-plugin figma と入力します。MCPサーバーだけを手で追加した場合、スキルは入りません。

use_figmaがツール一覧に出ないときの確認順

読み取り系は動くのにuse_figmaだけが無い、という報告はFigmaの公式フォーラムにもあります。FAQとフォーラムの回答をもとに、次の順で確かめます。

1. デスクトップ版のサーバーを使っていないか。公式は、リモート専用のツールが無いときはクライアントがデスクトップ版を使っている可能性を挙げています。エージェントに「どのFigma MCPサーバーを使っているか」と聞き、両方を登録しているなら接続先を確かめます。
2. クライアントが書き込みに対応しているか。上の22種に入っていなければ出ません。
3. リモートサーバーを入れ直す。新しいツールは、既存の設定を入れ直さないと出ない場合があるとFigmaのサポートが回答しています。
4. 出ても書き込みで失敗するなら、whoami でシートとプランを確かめます。

figma-useスキルの読み込みと公式スキルの組み合わせ

公式リポジトリ figma/mcp-server-guide の figma-use は、説明文の冒頭で「use_figmaを呼ぶ前に毎回必ず読み込むこと」と指定しています。FAQも、use_figmaとfigma-useは「両方必要」と書いています。多くのクライアントでは /figma-use <依頼内容> で明示的に呼び出せます。スキルの「Critical Rules」から、失敗につながりやすいものを挙げます。

• テキストを変える前に figma.loadFontAsync() を await する。既存のテキストは、決め打ちの書体でなく現在の書体を読み込む
• ページは await figma.setCurrentPageAsync(page) で切り替える。figma.currentPage = page はエラーになる。切り替えは1回の呼び出しにつき1回まで
• 色は0〜1の範囲で指定する。fillsとstrokesは読み取り専用の配列なので、複製してから代入し直す
• 変数を作るときは scopes を明示する。既定の ALL_SCOPES のままだと、すべてのプロパティの候補に出る

10月のスキルは、見た目が変わる書き込みのときは figma-generate-design を、再利用するコンポーネントや変数を作るときは figma-generate-library を一緒に読み込むよう求めています。use_figmaの skillNames パラメータは使ったスキル名の記録用で、実行結果には影響しません。

2026年10月20日時点のリポジトリの skills/ には16のスキルがあります。use_figmaの上で動くものは、FigJam用の figma-use-figjam、Slides用の figma-use-slides、キーフレームでノードを動かす figma-use-motion、仕様書を扱う figma-spec です。アニメーション機能そのものはFigma Motionとは？使い方・書き出し・無料でできる範囲を解説で扱っています。

use_figmaに渡すスクリプト例と送信前の型チェック

以下の4本は、公式スキル同梱の型定義 plugin-api-standalone.d.ts（2026年10月20日のコミット）に対し、TypeScript 7.0.2で型エラーが出ないことを確かめたものです。あわせて、素のJavaScriptとして node --check で構文エラーが無いことも確かめています。use_figmaは素のJavaScriptを受け取るので、string[] のような型注釈は書きません。Figma上での実行は確かめていません。

書き込む前にページと変数コレクションを読み出す調査スクリプト

公式スキルが最初の手順に置いているのが、ファイルの構造を読むことです。既存の命名や変数の体系に合わせないと、ライブラリと食い違うノードが増えます。

const pages = figma.root.children.map(p => ({ id: p.id, name: p.name, children: p.children.length }));
const collections = await figma.variables.getLocalVariableCollectionsAsync();
return {
  editor: figma.editorType,
  pages,
  collections: collections.map(c => ({
    id: c.id,
    name: c.name,
    variables: c.variableIds.length,
    modes: c.modes.map(m => m.name),
  })),
};

figma.editorType は、Designなら figma、FigJamなら figjam、Slidesなら slides を返します。応答は20KBまでなので、返す項目はIDと名前と件数に絞ります。

スペーシング変数を作りscopesをGAPに絞る書き込みスクリプト

const collection = figma.variables.createVariableCollection('Spacing');
const modeId = collection.modes[0].modeId;
const createdVariableIds = [];
const specs = [
  { name: 'space/4', value: 4 },
  { name: 'space/8', value: 8 },
  { name: 'space/16', value: 16 },
];
for (const { name, value } of specs) {
  const v = figma.variables.createVariable(name, collection, 'FLOAT');
  v.scopes = ['GAP'];
  v.setValueForMode(modeId, value);
  createdVariableIds.push(v.id);
}
return { collectionId: collection.id, createdVariableIds };

scopes を GAP に絞ると、この変数はAuto Layoutの間隔を指定する欄にだけ候補として出ます。返した変数のIDは、次の呼び出しで文字列として使います。

Auto Layoutの空状態カードを既存ノードの右側に置く配置スクリプト

const page = figma.root.children.find(p => p.name === 'Settings');
if (!page) throw new Error('Settings page not found');
await figma.setCurrentPageAsync(page);
await figma.loadFontAsync({ family: 'Inter', style: 'Regular' });
const right = Math.max(0, ...page.children.map(n => n.x + n.width));
const card = figma.createAutoLayout('VERTICAL');
card.name = 'Card/Empty state';
card.x = right + 100;
card.itemSpacing = 8;
card.paddingTop = card.paddingBottom = card.paddingLeft = card.paddingRight = 24;
const title = figma.createText();
title.fontName = { family: 'Inter', style: 'Regular' };
title.characters = '通知はまだありません';
card.appendChild(title);
title.layoutSizingHorizontal = 'HUG';
return { createdNodeIds: [card.id, title.id], width: card.width, height: card.height };

このスクリプトは公式スキルの規則を4つ守っています。ページの切り替えは1回だけ、フォントは文字を入れる前に読み込んで fontName にも同じ書体を指定する、新しいノードは座標(0,0)を避けて既存ノードの右側に置く、HUG は親のAuto Layoutに追加してから指定する、の4つです。最後の点は順序を逆にすると実行時エラーになります。複数回に分けて組むときは、外枠に placeholder = true を付けておくと作業中の印（光る表示）が出ます。終わったら必ず false に戻します。

query()で既存のカードの間隔を変数に紐づけるスクリプト

10月のスキルは、CSSのセレクタに似た node.query() を使うよう勧めています。次の例は、Settingsページで名前が「Card」で始まるAuto Layoutのフレームを探し、前の呼び出しで作った space/8 の変数を間隔に紐づけます。ページの文脈は呼び出しごとに先頭へ戻るので、ここでも切り替え直します。VariableID:1:2 は前の呼び出しで返ったIDに置き換えます。

const page = figma.root.children.find(p => p.name === 'Settings');
if (!page) throw new Error('Settings page not found');
await figma.setCurrentPageAsync(page);
const space8 = await figma.variables.getVariableByIdAsync('VariableID:1:2');
if (!space8) throw new Error('space/8 not found');
const mutatedNodeIds = [];
for (const node of page.query('FRAME[name^=Card]')) {
  if (node.type !== 'FRAME' || node.layoutMode === 'NONE') continue;
  node.setBoundVariable('itemSpacing', space8);
  mutatedNodeIds.push(node.id);
}
return { mutatedNodeIds, count: mutatedNodeIds.length };

query() が返すのはノードの汎用型なので、node.type で絞り込まないと layoutMode に触れられません。スキルの規則にある「型ごとのプロパティに触る前に絞り込む」は、このことです。

tscで送信前に検査する方法と型定義が追いついていない2点

use_figmaの失敗の多くは、実行して初めて分かります。送る前に型で検査するなら、本体を async function で包み、先頭に型の宣言を足します。トップレベルの return のままだと、tscが TS1108 で止まるためです。

import type { PluginAPI } from './plugin-api-standalone';
declare const figma: PluginAPI;
export {};
async function main() {
  // ここにuse_figmaへ送るスクリプト本体を貼る（各行を字下げ）
}

上の4本は、この形に包んで tsc --noEmit --strict --target es2022 --lib es2022 --module esnext --moduleResolution bundler でエラーが出ないことを確認しています。逆に、次のスクリプトを同じ条件で検査すると結果が分かれます。

const col = figma.createAutoLayout('VERTICAL', { name: 'Column', itemSpacing: 8 });
const text = figma.createText();
col.appendChild(text);
text.layoutSizingVertical = 'AUTO';
col.counterAxisSizingMode = 'FILL';
col.set({ itemSpacinng: 8, counterAxisSizingMode: 'FILL' });
return col.id;

# 行番号は async function で包んだ後のファイルのもの（4行ずれる）
bad.ts(5,50): error TS2554: Expected 0-1 arguments, but got 2.
bad.ts(8,3): error TS2322: Type '"AUTO"' is not assignable to type '"FILL" | "FIXED" | "HUG"'.
bad.ts(9,3): error TS2322: Type '"FILL"' is not assignable to type '"AUTO" | "FIXED"'.
# 10行目の set({ itemSpacinng: 8, counterAxisSizingMode: 'FILL' }) はエラーにならない

1つ目に、スキル本文は figma.createAutoLayout('VERTICAL', { ... }) のように第2引数で設定を渡せると書いていますが、同梱の型定義は引数を1つしか受けないので TS2554 で落ちます。型で検査するなら、設定は作成後に1つずつ代入します。2つ目に、set() の引数は型定義上 Record<string, unknown> なので、itemSpacinng の綴り誤りも 'FILL' の取り違えも検出されません。列挙値は代入で書けば TS2322 で止まります。

use_figmaへのプロンプトの渡し方と呼び出しの分け方

リモートサーバーはリンクで対象を特定します。ファイル全体ならブラウザのアドレスバーのURL、特定のレイヤーなら右クリックの「Copy link to selection」で取ったリンクをプロンプトに入れます。write to canvasのページの例は「この選択範囲（リンク）の生の値を変数に置き換え、周囲のコンポーネントもその変数を使うように更新して」のような形です。使うライブラリ・コンポーネント・変数・モードの名前を明示するほど、既存の資産に沿った結果になります。

呼び出しの分け方は、公式ドキュメントと公式スキルで指針が違います。write to canvasのページは「大きな変更は少しずつ」と書いていますが、10月の figma-use は、確認のためだけに処理を細かく分けることをやめるよう指示しています。1ページ分をまとめて作ってよく、分けるのはページをまたぐとき、途中で失敗すると戻しにくいとき、実際に失敗して部分的にやり直すときです。複数ページの作業は、ページごとの呼び出しを並列に出すよう求めています。

use_figmaの制限：応答20KB・画像・フォント・ベータ品質

write to canvasが挙げるuse_figmaの5つの制限

write to canvasのページ（2026年10月20日更新）が挙げる現在の制限は5つです。

• 1回の呼び出しで返せる応答は20KBまで
• use_figmaだけでは新しい画像を追加できない。画像や動画を含むコンポーネントの取り込みと、GIFの作成も未対応
• フォントはFigmaアカウントにアップロードされている必要がある。手元のパソコンにだけ入っているフォントは使えない
• Code Connectの対応付けを完了するには、コンポーネントを手動で公開する必要がある
• 出力はベータ品質で、手作業の確認と手直しが要る場合がある

フォントの項目は、9月までは「カスタムフォントは未対応」と書かれていました。今は、独自の書体でもFigmaにアップロードしてあれば使えます。書体名は figma.listAvailableFontsAsync() で先に確かめます。スキルは「SemiBold」と「Semi Bold」の取り違えをよくある失敗に挙げています。

画像の追加・生成・取得に使うupload_assets・generate_image・download_assets

use_figmaは、ファイルにすでにある画像を別のノードに付け替えることはできますが、外部の画像を持ち込めません。ツール一覧によると、画像は次のツールで扱います。

• upload_assets：PNG・JPG・GIF・WebP・SVGを、1ファイル10MBまで、1回60ファイルまで配置する。SVGは画像の塗りではなく編集できるベクターになる
• generate_image：説明文から画像を生成して配置する。画像ごとにFigmaのAIクレジットを使う
• download_assets：1回20ノードまで、PNG・JPG・SVG・PDFで書き出し、塗りに使われた元画像（JPEG・PNG・GIF・WebP）もそのまま取り出す

書き出しの形式にWebPはありません。WebPで受け取れるのは、元からWebPでアップロードされた画像を原本のまま取り出すときだけです。Webアプリの画面に写真やアイコンがある場合、figma-generate-design は、generate_figma_design で画面を取り込み、そのレイヤーの imageHash をuse_figmaで作ったフレームの塗りへ移す手順を必須にしています。足りない画像だけを generate_image で補います。

use_figmaのレート上限と料金

Figma MCPサーバーの呼び出し上限は、プランとシートの組み合わせで決まります。2026年10月23日時点のRate limits & accessの値は次のとおりです。

EducationはProfessionalのFull・Devと同じです。use_figmaで書き込むのはFull（下書きならDev）なので、関係するのは右の列です。料金を含めた全体像はFigma MCPサーバーの料金と上限にまとめています。

use_figmaが上限に数えられるかどうかは、公式の書き方からは確定しません。同じページは、上限がかかるのは読み取り系のツールで、書き込み系のツールを含む一部は対象外だと書いています。ところが対象外として名前が挙がっているのは add_code_connect_map・create_new_file・generate_figma_design・whoami の4つで、use_figmaは入っていません。use_figmaは読み取りのスクリプトも実行できるので、見積もりでは上限に数えられる前提で置くのが安全です。

数値の食い違いも残っています。公式リポジトリのREADMEは、StarterプランとView・Collabシートを今も「月6回まで」と書いており、開発者ドキュメントの月20回と合いません。

料金は、ベータ期間中は無料です。公式は、キャンバスへの書き込みを将来、従量課金の有料機能にすると書いています。単価と開始時期は2026年10月23日時点で公表されていません。

use_figmaのエラー対処：safeToRetryWithoutCanvasReadと頻出エラー

use_figmaがエラーを返したら、まずエラーに付いている safeToRetryWithoutCanvasRead を見ます。true なら、原因を直してそのまま再実行して構いません。false なら途中まで書き込まれている可能性があるので、キャンバスを読み直して何が変わったかを確かめてから次の変更をかけます。同じAPIのエラーが2回続いたら、処理を細かく分けるのではなく、型定義で該当箇所を1回調べて原因を直すのがスキルの指示です。

スクリプトは成功したのに見た目がおかしい場合は、構造を get_metadata、見た目を get_screenshot で確かめ、壊れた部分だけを直すスクリプトを送ります。全体を作り直すと、正しかった部分のIDまで変わります。

use_figmaを採用しないほうがよい条件

use_figmaが力を出すのは、既存のコンポーネントと変数を組み合わせて画面を増やす作業です。次の条件では、採用を見送るか範囲を絞るべきです。

1つ目は、デザインシステムが整っていないファイルです。公式が強調しているのは「既存のコンポーネントや変数で組める」点です。どちらも無いファイルでもuse_figmaで変数やコンポーネントから作れますが、それはデザインシステムを作る作業で、画面を増やす作業とは別です。再利用する構造が要らない1回限りの画面なら、ライブラリとつながらない html_to_figma のレイヤーで足ります。

2つ目は、仕上がりの精度がそのまま成果物になる作業です。公式は出力を「ベータ品質」と書き、本番ファイルの前に複製か下書きで試すよう勧めています。レビューの時間を確保できないなら、出力は下書き止まりにします。

3つ目は、書き込む人の多くがDev・View・Collabシートのチームです。下書きの外に書くにはFullシートが要るので、書き込む人の数だけFullシートの費用がかかります。Code Connectはコードとコンポーネントを対応付ける機能で、デザインは書き換えません。Professionalプランでも使えますが、Code ConnectのヘルプによるとProfessionalで有効にできるライブラリとフレームワークはそれぞれ1つです。REST APIの変数エンドポイントは、今もEnterpriseプランのFullシートが条件です。Code Connectの設定はFigma Code Connectの使い方、REST APIで変数を扱う方法はFigma APIの使い方で解説しています。デザインシステムをFigmaとコードの両方で整える段階から相談したい場合は、UI/UXデザインの支援も用意しています。

よくある質問

use_figmaとは何ですか？

Figma MCPサーバーの書き込み用ツールです。AIエージェントが書いたJavaScriptをFigmaファイルのなかでPlugin API経由で実行し、フレーム・コンポーネント・バリアント・変数・Auto Layoutを編集できるデータとして作成・変更します。対象はFigma Design・FigJam・Figma Slides・Figma Specsです。リモートサーバー（https://mcp.figma.com/mcp）専用です。

use_figmaは無料で使えますか？

2026年10月23日時点ではベータ期間中のため、追加料金はかかりません。ただしFigmaは、キャンバスへの書き込みを将来、従量課金の有料機能にすると公式に明記しています。単価と開始時期はまだ公表されていません。書き込みに使うFullシートの費用と、画像生成に使うAIクレジットは別にかかります。

Devシートでもuse_figmaで書き込めますか？

自分の下書きのファイルには書き込めます。下書き以外のファイルに書くにはFullシートが必要で、Devシートではデザインのコンテキスト・スクリーンショット・メタデータ・変数を読む用途に限られます。ファイルの編集権限も必要です。どのシートで認証されているかは、whoamiツールで確かめられます。

Figma MCPの上限・レート制限はuse_figmaにもかかりますか？

公式の記述からは確定しません。上限は読み取り系のツールにかかり、書き込み系を含む一部のツールは対象外とされていますが、対象外として名前が挙がっているのはadd_code_connect_map・create_new_file・generate_figma_design・whoamiの4つで、use_figmaは入っていません。見積もりでは、Full・Devシートの1日200回（Enterpriseは600回）に数えられる前提で置くのが安全です。

figma-useスキルとは何ですか？

Figmaが公式リポジトリ figma/mcp-server-guide で配布している、use_figma用のエージェントスキルです。フォントの読み込み、ページの切り替え方、色の範囲、Auto Layoutの指定順、変数のscopesといった、Plugin APIでつまずきやすい規則をまとめています。Claude CodeやCursorでは、Figmaプラグインを入れると一緒に導入されます。

関連記事

• Figma MCPサーバーの料金と上限｜無料枠・プラン別の呼び出し回数・接続手順
• Figma Code Connectの使い方｜UIとCLIの始め方とDev Mode表示・CLI v2移行
• Figma APIの使い方｜APIキー発行・レート制限の実数・Variables REST APIの条件【2026年10月】
• FigmaをReactに変換する4つの方法｜HTML書き出しの可否とMCP・Figma Make・エージェント・Locofyの使い分け【2026年10月】
• Figma Makeの料金とAIクレジット｜残量の確認方法・プラン別上限・追加購入【2026年10月】