figsnap-mcp

Figsnap MCP

開いているFigmaファイルをMCPツールとして利用できます。それ以外の機能はありません。

claude mcp add figsnap-mcp -s user -- npx -y figsnap-mcp

これらをインストールすると、MCP サーバーが導入されます。デーモンが実行中でFigmaプラグインが開いていない限り、何も応答しません。起動方法をご覧ください。5つの手順で、所要時間は約2分です。

Figmaプラグイン、ローカルデーモン、MCP サーバーで構成されています。コーディングエージェントはデザインを読み取り、ノードをPNG、React、HTML、CSSとして抽出し、許可があればキャンバスを編集し、保存済みのコンポーネントセットを共有します。中継もアカウントもなく、ループバック以外のネットワーク通信もありません。

  MCP client              figsnap-mcp              daemon                 the plugin
  (Claude Code)   stdio    (stateless      HTTP :3058       ws         (open in Figma)
       ─────────────────►   proxy)          ──────────►   /panel   ──────────►   figma.*
                                            127.0.0.1 only

3つのプロセスと1つのルールがあります。figma.*が存在するのはプラグインが開いている間だけです。そのため、接続を維持するのはプラグインで、それ以外はその接続を通じて問い合わせます。

これは何ではないか

このリポジトリはFigsnapを派生させ、1つの役割に絞ったものです。Figsnapは1つのpackage.jsonから、プラグイン、アカウント機能付きのCloudflare Workerリレー、ACPチャットクライアント、そしてこのMCP サーバーの4つの製品を提供します。MCPツールと保存済みのセットだけが必要な場合でも、すべてをクローンし、開くことのない4,200行のパネルをビルドし、ログインすることのないWorkerを許可リストに登録したマニフェストを持つプラグインを読み込む必要がありました。

つまり、**ACPクライアント、ハーネスの検出、セッションストア、リレー、アカウント、チャット、APIブラウザー、コードエクスポートUIはありません。**残されているのは、抽出エンジン、41個のツール、3つのペインを備えたパネルです。

この変更によってFigsnapに手が加えられることはなく、2つを並行して実行できます。このデーモンはポート3058を使用し、トークンは~/.figsnap-mcp/agent-tokenに保存されます。一方、Figsnapはポート3056を使用し、トークンは~/.figsnap/agent-tokenに保存されます。

ただし、マニフェストには注意が必要です。FigmaはallowedDomainsを検証し、IPリテラルを拒否します。Invalid value for allowedDomains. 'ws://127.0.0.1:3058' must be a valid URLというエラーになります。拒否されたマニフェストは読み込まれず、プラグインはひっそりと最後に正常に読み込まれたマニフェストを使い続けます。名前にはlocalhostを指定し、ここで変更を加えた後はコンソールを確認してください。ほかにエラーを知らせる手段はありません。

Figma内でも、この2つは分離されています。clientStorageはプラグインIDごとに管理されるため、このマニフェストにはFigsnapのREPLACE_ON_PUBLISHではなく独自のIDが設定されており、このプラグインが書き込むすべてのキーには、その上でfigsnap-mcp:というプレフィックスが付いています。どちらか一方の保存領域を共有すると、デーモンアドレスも共有されます。その結果、ws://localhost:3056を引き継いだパネルは、独自のマニフェストのCSPによってブロックされます。デザイナーには見えないコンソールエラーも発生します。また、パネルは保存済みまたは入力されたアドレスがマニフェストで許可されたポート以外の場合、それを拒否し、併せて渡されたトークンも破棄します。

インストール

npm install -g figsnap-mcp

2 つのコマンドがインストールされます。

figsnap-mcp-daemon	ブリッジです。作業中は起動したままにします
figsnap-mcp	クライアントが起動する MCP サーバーです。手動では実行しません

インストールを省略して npx に取得させることもできます。通常、MCP クライアントの設定ではこの方法を使います。Figma プラグインもパッケージに同梱されています。グローバルインストール後、そのマニフェストは次の場所にあります。

npm root -g   # …/lib/node_modules — the manifest is figsnap-mcp/manifest.json

または、リポジトリをクローンして npm install && npm run build を実行します。これは、ソースを同じ場所に置いたまま同じ処理を行う方法です。

起動方法

最初に一度だけ、5 つの手順を行います。

1. ビルドします。

npm install -g figsnap-mcp

クローンからの場合は、代わりに npm install && npm run build を実行します。

2. デーモンを起動します。 起動したままにしてください。Figma と通信するのはこれだけです。

figsnap-mcp-daemon                # --allow-edits opens the writing tools at boot

クローンからの場合は、npm run daemon を実行します。その他のオプションは figsnap-mcp-daemon --help で確認できます。

アドレスとトークンが出力されます。

figsnap-mcp-daemon 0.1.0
  panel socket   ws://127.0.0.1:3058/panel
  http           http://127.0.0.1:3058
  token          8fT2qN4vRk1pXwLzYc7BhJ0mAeUdSg9T
  edits          off — turn them on in the plugin, or start with --allow-edits

3. プラグインを読み込みます。 Figma デスクトップで、Plugins → Development → Import plugin from manifest を選択し、パッケージの manifest.json を指定します（npm root -g で場所を確認できます。リポジトリのルートにもあります）。次に Figsnap MCP を実行します。

4. パネルをペアリングします。 手順 2 の token 行をコピーし、パネルの Connect ペインに貼り付けて Connect を押します。ドットが緑色に変わり、Address に ws://localhost:3058/panel と表示されます。

トークンを入力するのはここだけです。Figma 独自のユーザーごとのストレージに保存されるため、以降はパネルが毎回自動的に再接続します。

5. MCP サーバーを登録します。

claude mcp add figsnap-mcp -s user -- npx -y figsnap-mcp

クライアントを再起動すると、claude mcp list に figsnap-mcp · ✔ Connected と表示されます。クローンからの場合は、ファイル名を指定します。-- node /path/to/FigsnapMCP/agent/mcp-stdio.mjs

接続全体を確認します。

curl -s http://127.0.0.1:3058/health
# { "ok": true, "panelConnected": true, "editsAllowed": false, ... }

重要なのは panelConnected: true の行です。これは、もう一方で Figma が接続されていることを意味します。

トークン

MCP クライアントがトークンを必要とすることはありません。 ここが意外に思われる点です。claude mcp add にトークンも環境変数も設定も必要ありません。MCP サーバーは、処理の途中でデーモン自身のファイルを読み取ります。

トークンを使うものは 2 つだけで、そのうち 1 つを使うのはあなた自身です。

対象	取得方法
Figma パネル	Connect に一度だけ貼り付けます
agent/mcp-stdio.mjs	~/.figsnap-mcp/agent-token を自動的に読み取ります

トークンの生成元。 デーモンを初めて起動したときに、24 個のランダムバイトからなるトークンが 1 つ生成され、base64url 形式に変換されて、モード 600 で ~/.figsnap-mcp/agent-token に書き込まれます。次回以降の起動では同じファイルが読み込まれるため、トークンは変わらず、毎朝パネルを再ペアリングする必要もありません。

再起動せずにトークンを再確認する方法：

cat ~/.figsnap-mcp/agent-token

トークンがある理由。 デーモンはループバックポートで待ち受けますが、アクセスしたウェブページはどれでも localhost へのソケットを開けます。これを防ぐものが 2 つあります。アップグレード時に確認され、ブラウザーでは偽装できない Origin ヘッダーと、ブラウザーの WebSocket では設定できないこのトークンです。トークンなしでアクセスできるのは GET /health だけです。そのため、パネルはペアリング前でもデーモンが起動していることを確認できます。

トークンが漏えいした場合は、ローテーションします。

npm run daemon -- --new-token

新しいトークンが書き込まれ、古いトークンは無効になります。Connect に新しいトークンを貼り直してください。MCP クライアントはファイルを読み込むため、自動的に新しいトークンを使います。

独自のトークンを使う場合（たとえば、スクリプトで固定トークンを使う場合）は、FIGSNAP_MCP_TOKEN を設定すると、デーモンはファイルの代わりにそのトークンを使います。MCP クライアントがホームディレクトリを読み取れない場合は、同じ変数を設定してください。FIGSNAP_MCP_URL を設定すると、クライアントが接続するアドレスを変更できます。

MCP クライアントの接続設定

claude mcp add figsnap-mcp -s user -- npx -y figsnap-mcp

JSON を受け取るクライアントの場合：

{ "mcpServers": { "figsnap-mcp": { "command": "npx", "args": ["-y", "figsnap-mcp"] } } }

figsnap-mcp-daemon --mcp を実行すると、パスが入力済みの両方の設定が出力されます。

その後、claude mcp list に figsnap-mcp · ✔ Connected と表示されるはずです。また、セッションでは figma_get_selection がキャンバスで選択されている内容について応答します。

応答がない場合

問題は3つ考えられ、それぞれ異なるメッセージが表示されます。

ツールのメッセージ	対処方法
No figsnap-mcp daemon at http://127.0.0.1:3058	npm run daemon
The Figsnap MCP plugin is not open in Figma	ファイルを開いてプラグインを実行します
The figsnap-mcp daemon rejected the token	cat ~/.figsnap-mcp/agent-token を実行するか、FIGSNAP_MCP_TOKEN を設定します
Editing the file is switched off	プラグインの「Tools」ペインで Allow edits をオンにします

リソース

Figma ファイルについて質問するときにほぼ必ず必要になる3つの項目は、呼び出すのではなくアドレスで指定できるため、クライアントから @ でメンションできます。

URI	内容
figma://selection	選択中の項目をすべて抽出したもの
figma://page	3階層分のレイヤーツリー
figma://library	ID 付きのコンポーネント、スタイル、変数
figma://node/{nodeId}	1つのレイヤー — figma://node/21:10314

パネル

ペインは4つあり、起動時に開くのは Selection です。

Selection には、キャンバスで選択した項目のプレビューが表示されます。画像、名前、種類、サイズ、子要素の数、ノード ID に加えて、フォルダー選択ボタンと Save ボタンがあります。ここから保存すれば、ペインを切り替えたり、リストからレイヤーを探し直したりする必要がありません。

プレビューでは PNG を1回エクスポートします。以前は選択が変わるたびに、誰も見ていない画像に対して HTML、TSX、2つのスタイルシート、2倍サイズの画像を含む完全な抽出を実行していました。MCP が必要とするコード出力は、クリックのたびに生成するのではなく、リクエストに応じて生成します。小さなレイヤーは最大4倍まで拡大されるため、アイコンと画面のどちらもステージいっぱいに表示されることはありません。

Minimise（右上の ▼）をクリックすると、ウィンドウが高さ44pxの帯になり、その下にプレビューが表示されます。プラグインを動かしたままキャンバスを見やすくできます。デーモンの動作にはパネルを開いておく必要がありますが、見る必要はありません。帯には選択中の項目名と Save ボタンが引き続き表示されます。作業中に必要なのはこの2つだからです。▲ をクリックすると、ドラッグして設定したサイズに戻ります。

Connect と Tools はペアリングとツール一覧、Saved はフォルダーマネージャーです。どちらも以下で説明します。

ツール

41 個あります。14 個は Figma の読み取り、26 個は Figma への書き込み、1 個はデーモン内で応答します。 Tools ペインにはすべてのツールが表示され、書き込み可能なものには印が付いています。GET /tools からも同じリストを JSON 形式で取得できます。

読み取りは常に許可されています。書き込みは、許可するまでできません。変更を加えるすべてのツールは、Allow edits がオンになるまで拒否されます。これはデザイナーが操作するスイッチであり、エージェントがプロンプトをうまく回避して通過できるものではありません。権限プロンプトを無効にして実行するハーネスでも、この制限は回避できません。ターミナルで作業する場合は、--allow-edits を指定すると同じ制限を解除できます。

41 個のツールの説明がリクエストごとに実際のコンテキストを消費するため、2 つのツールでは 13 個のプラグインコマンドを、それぞれ 1 つの引数にまとめています。

• figma_extract は、単一の nodeId のほか、一括処理用に nodeIds、urls、selection: true、saved: true を受け取ります。
• figma_saved は、action として list、folders、save、unsave、clear、move、newFolder、renameFolder、deleteFolder を受け取ります。

画像は実際の画像ブロックとして返され、テキストフィールド内の Base64 にはなりません。ノードごとに画像を取得するには figma_export_png を使います。

figma_ios_spec は CSS ではなく、Figma が実際に保持しているプロパティをポイント単位で返します。軸ごとのサイズ指定、自動レイアウトとそのパディング、線の太さと配置、角のスムージング、エフェクト、テキストブロックに加え、すべての塗りと線に painted の状態が記されます。コードに落とし込む段階で使ってください。figmaCss はノードが Web 上でどのように見えるかを示しますが、実装に必要な情報が抜け落ち、実際には描画されない塗りも報告されます。たとえば、オフになっている線も border: 1px solid として返されます。ここでの線には layoutFrame と visualFrame の両方が含まれます。これは、CENTER の線は太さの半分が境界の外側に配置される一方、UIKit では境界線が内側に描画されるためです。また、エフェクトには uikitShadowRadius が含まれ、その値はぼかしの半分です。

制限が 1 つあります。グラデーションの塗りでは、種類、透明度、painted フラグは返されますが、停止点は返されません。そのため、グラデーションがあることは分かっても、再現はできません。現時点では、その色は figma_export_png から読み取ってください。

figsnap_skill は例外です。プラグインを使わないため、Figma を閉じた状態でも応答します。check は、このパッケージに同梱されているスキルがこのプロジェクトにあるかどうかを返します。結果は missing、current、または modified のいずれかです。コピーは編集できますが、編集済みの場合はユーザー自身のものとして報告され、置き換えられることはありません。install はファイルと配置先を返します。呼び出し元はリポジトリへの書き込み前にすでに確認を求めるため、ここではファイルを書き込みません。対象となるプロジェクトは MCP クライアント自身のディレクトリで決まり、その場所は mcp-stdio.mjs が呼び出しごとに指定します。デーモンの場合は起動した場所であり、通常は作業中の場所とは異なります。

保存済みセット

Saved ペインは、何度も使うコンポーネントを保存する場所です。フォルダー、Save selection、ノードへの移動、フォルダー間の移動、削除を利用できます。MCP からは figma_list_saved と figma_saved でアクセスできるため、ユーザーとエージェントは同じリストを参照できます。

これはドキュメント ID をキーとして figma.clientStorage に保存されます。つまり、ユーザーごと、ファイルごと、マシンごとです。最大 100 件、フォルダーは最大 30 個で、階層は 1 段までです。

意図的に失われるものが 1 つあります。 Figsnap はこのセットをリレーにもミラーリングするため、2 台目のマシンでも利用できます。Worker がなければ、これらのセットはローカルにのみ保存されます。このリポジトリでは、それが適切なトレードオフです。アカウントもネットワークも不要で、閲覧のみ可能なファイルでも常に書き込めます。ただし、これは実際の違いです。後からデバイス間の同期が必要になった場合も、追加の変更だけで実現できます。プラグインに同期先を追加するのであって、データの新たな所有者を作るわけではありません。

レイアウト

index.mjs              the library entry point; importing it starts nothing
index.d.mts            hand-written types for it
manifest.json          the Figma plugin manifest; localhost:3058 only
build.mjs              esbuild → dist/code.js + a self-contained dist/ui.html
shared/                nodes.mjs (findable types), shape.mjs (what a body means)
agent/
  index.mjs            the daemon: WS server, HTTP server, the Edits gate
  mcp-stdio.mjs        the MCP server; a stateless proxy to the daemon
  lib/tools.mjs        the 41 tools — one command each, no logic in between
  lib/skill.mjs        the skill on disk: the one tool answered without Figma
  lib/plugin-socket.mjs  the panel socket: origin check, token, request/response
  lib/http.mjs         /health, /tools, /tool
  lib/gate.mjs         the Edits switch
  lib/paths.mjs        the port, the host and the token file, defined once
src/
  code.ts              the main thread: 51 commands, extraction and codegen
  figma-css.ts         Figma's own CSS, rendered
  daemon.ts            the one address the plugin dials
  ui/                  the panel: bridge.ts, main.ts, index.html, style.css
test/                  run.mjs and five suites; see Tests below
.github/workflows/     CI on Node 20, 22 and 24; publish on a version tag

ライブラリとして使用する

ほとんどの方が必要とするのは、2 つのコマンドです。独自のブリッジを構築する場合、このパッケージではカタログと、デーモンの構成要素をエクスポートしています。

import { toolManifest, createGate, createPluginSocket, createHttpHandler } from 'figsnap-mcp'

console.log(toolManifest().length)  // 39

インポートしてもサーバーは起動せず、ソケットも開きません。agent/mcp-stdio.mjs は読み込まれた時点で MCP サーバーを標準入出力に接続するため、意図的に再エクスポートしていません。また、以前そこにあった定数は agent/lib/paths.mjs にあります。index.d.mts は手書きで、テストスイートでは実行時の内容との整合性を両方向からチェックしています。

Semver は 1.0.0 から適用されます。0.x の間は、ファクトリーが最も変更される可能性の高い部分です。カタログと定数は安定した部分です。

セキュリティ

デーモンは 127.0.0.1 のみでバインドし、ソケットは 2 つの仕組みで保護されます。ローカルポートには、アクセスしたページのいずれからも接続できるためです。

• オリジン：アップグレード時にチェックします。プラグインの iframe はサンドボックス化されたドキュメントであり、null を送信します。エディターは figma.com を送信します。それ以外はすべて 4001 で閉じられます。ブラウザーではこのヘッダーを偽装できず、アップグレードには CORS が適用されないため、これが重要なチェックとなります。
• トークン：ブラウザーの WebSocket ではヘッダーを設定できないため、クエリ文字列に含めます。HTTP の呼び出し元が送信する x-figsnap-token と同じトークンです。トークンなしでアクセスできるのは /health のみなので、パネルはペアリング前に接続を確認できます。

トークンが漏洩した場合は、--new-token でローテーションできます。

テスト

npm test          # four suites: no wrangler, no network, no Figma
npm run typecheck

• e2e-plugin.mjs は、配布されている dist/code.js を偽の figma に対して実行し、実際のデーモンに接続して、POST /tool 経由で操作します。抽出の忠実性、figma_find_nodes、リロードを含む保存セット、ゲートを閉じた場合と開いた場合の書き込みを確認します。
• e2e-mcp.mjs はデーモンを起動し、パネルを WebSocket クライアントとして偽装して、実際の MCP クライアントを標準入出力経由で操作します。ガード、ツール一覧、バッチと画像のルール、10 個すべての保存セットコマンド、リソース、および Figma に到達する前に呼び出しが失敗する 3 つのパターンを確認します。
• e2e-panel.mjs は、メインスレッドとデーモンを置き換えた状態で、配布されている dist/ui.html を jsdom に読み込み、デザイナー側の操作を確認します。各ペインは受け取った内容を表示し、クリックは表示どおりに機能し、破壊的なフォルダー操作は実行前にアームされます。
• contract.mjs は不整合を防ぐためのガードです。shared/、agent/lib/tools.mjs、src/code.ts はこのリポジトリと Figsnap の両方に存在し、それらの間のプロトコルには共有型がありません。そのため、片側だけの編集で壊れる内容をチェックします。ツールが指定できるすべてのコマンドが src/code.ts のケースに対応していること、すべてのケースにツールから到達できること、MAX_BATCH が一致すること、パネルが表示する上限値とプラグインが適用する上限値が一致すること、find_nodes スキーマが FINDABLE_TYPES だけを提示すること、3 つのファイルすべてで 3058 が一致すること、そしてリレー、アカウント、ACP クライアントがいつの間にか再インポートされていないことを確認します。

プラグインを組織に公開する

プラグインは開発版としてインストールしたままでもかまいません。マニフェストをインポートすれば完了です。ただし、Figma の組織に公開すると、プラグインが全員のプラグイン一覧に表示され、自動的に更新されます。コミュニティには表示されません。

この方法を利用するには、Figma のOrganization または Enterpriseプランが必要です。Professional で公開できるのは、公開状態になるコミュニティのみです。そのため、非公開で利用するには開発版としてインストールします。

1. まずビルドします：npm run build。Figma が公開するのは src/ の内容ではなく、dist/ にあるファイルです。
2. Figma デスクトップ → プラグイン → 開発 → Figsnap MCP → 公開。
3. コミュニティではなく、 のみを選択します。
4. 掲載情報を入力します：128×128 のアイコン、説明、カバー画像。組織限定の公開ではコミュニティの審査を省略できるため、送信するとすぐに公開されます。

初回の公開時に、Figma は manifest.json にプラグイン ID を書き込み、REPLACE_ON_PUBLISH_FIGSNAP_MCP を置き換えます。この変更をコミットしてください。これにより、以降のバージョンは新しいプラグインではなく更新として識別され、また、このプラグインの clientStorage が Figsnap のものと分離されます。更新をリリースするには、再度ビルドし、同じメニューからもう一度公開します。

明確にしておきたい点がひとつあります。このリポジトリと npm パッケージは公開されており、どちらにもビルド済みのプラグインが含まれています。組織限定の公開で制御できるのは、Figma 内での掲載と配布であり、コードを入手できるユーザーではありません。いずれの場合も、ライセンスは MIT です。

リリース

CI は、プッシュごとに Node 20、22、24 でテストスイートを実行します。

最初のリリースは手動で行います。npm では、パッケージ固有の設定ページで信頼された公開元を設定する必要がありますが、パッケージが存在するまではそのページがないためです。

npm login
npm publish --access public

次に、信頼された公開を一度だけ有効にします。npmjs.com/package/figsnap-mcp/access → Trusted Publisher → GitHub Actions の順に進みます。

フィールド	値
Organization または user	arimunandar
Repository	figsnap-mcp
Workflow filename	publish.yml
Environment name	空欄のまま

以降のリリースはすべてタグで行います。

npm version patch          # writes package.json and the v0.1.1 tag
git push --follow-tags

npm version は scripts/sync-server-json.mjs も実行します。このスクリプトは、新しいバージョンを server.json の 2 つのバージョンフィールドにコピーしてステージングするため、3 つすべてが同じコミットに含まれます。ワークフローは、それらが一致しないリリースを拒否します。これにより、0.2.0 がレジストリに公開される前に問題を検出できました。

.github/workflows/publish.yml はタグを検出し、package.json の内容と一致しない場合は拒否します。また、OIDC による来歴情報付きで公開します。漏えいするトークンは存在しません。これは、npm が 2FA を回避できるトークンを制限しているため重要です（アカウント変更は 2026 年 8 月、直接公開は 2027 年 1 月）。

prepublishOnly は、型チェック、ビルド、すべてのテストスイートを実行してから公開するため、正常に動作しないリリースがレジストリに届くことはありません。npm pack --dry-run で送信される内容を正確に確認でき、test/e2e-package.mjs がその内容を検証します。

ライセンス

MIT。