Figma MCP Server

Figma MCP サーバー（Apify Actor）

AI アシスタント（Cursor、Claude、カスタムエージェント）に Figma REST API の機能を提供する Model Context Protocol（MCP）サーバーです。Apify プラットフォーム上で長時間稼働するウェブサーバー（スタンバイ／コンテナー URL）として、またはローカルで apify run を使って実行できます。

機能

• ファイル分析 — 構造、メタデータ、スタイル、深さを制限したツリー
• コンポーネント — 一覧、詳細、使用状況
• アセット — ノードのエクスポート（PNG、SVG、PDF、JPG）
• コメント — 読み取りと作成
• プロジェクト／チーム — 一覧とメタデータ
• ガイド付きワークフロー向けの MCP リソースとプロンプト

認証

Personal Access Token（デフォルト）

個人利用におすすめです。Actor の入力で figmaAccessToken を設定するか、環境変数で FIGMA_ACCESS_TOKEN を設定します。

• 生成先：Figma → Settings → Security → Personal access tokens
• API ヘッダー：X-Figma-Token
• PAT が設定されている場合、API 呼び出しでは OAuth が無効になります（また、/oauth/* ルートはエラーを返します）。

OAuth 2.0（任意 — チーム／共有ファイル）

figmaAccessToken を省略し、Figma OAuth アプリを指定する場合に使用します。

入力	目的
oauthClientId	Figma → Developers → Apps から取得
oauthClientSecret	同じアプリのもの
oauthRedirectUri	アプリに登録した正確なリダイレクト URL（例：https://<your-run>.runs.apify.net/oauth/callback）
oauthScopes	任意。カンマ区切りのスコープ。アプリに設定されたスコープの一部である必要があります。デフォルトには file_content:read、file_content:write、file_comments:read、file_comments:write が含まれます。

フロー

1. OAuth フィールドを入力し、PAT は設定せずに Actor を起動します。
2. ブラウザー（通常のブラウザー。埋め込み WebView は不可。Figma の要件）で GET https://<container-url>/oauth/authorize を開きます。
3. 同意後、Figma は /oauth/callback にリダイレクトします。トークンは実行のデフォルトの キーバリューストア（FIGMA_OAUTH_SESSION）に保存され、有効期限が近づくと更新されます。

トークン交換には、Figma のドキュメントに記載されたエンドポイント（https://api.figma.com/v1/oauth/token と .../oauth/refresh）を使用します。認証コードの有効期限は短いため、速やかにリダイレクトを完了してください。

要件

• Node.js ≥ 20
• Apify アカウント（クラウドで使用する場合）
• Figma の PAT および／または OAuth アプリ

クイックスタート（Apify Cloud）

npm install
apify login
apify push

Apify Console で Actor を開き、入力（最低限 figmaAccessToken）を設定して、テンプレートに必要な ウェブサーバー／長時間稼働 モードで起動し、実行から Container URL を使用します。

デプロイの参考：apify push でビルドして公開します。Apify CLI を参照してください。

設定（入力）

パラメーター	型	デフォルト	説明
figmaAccessToken	string	—	PAT（推奨）。 設定すると、すべての Figma API 呼び出しで使用されます。
port	integer	8080	HTTP リッスンポート（Apify が web_server_port で上書きする場合があります）。
oauthClientId	string	—	OAuth アプリのクライアント ID（PAT を使用しない場合のみ）。
oauthClientSecret	string	—	OAuth アプリのシークレット（シークレット入力）。
oauthRedirectUri	string	—	Figma アプリのリダイレクト URI と完全に一致する必要があります。
oauthScopes	string	—	任意のスコープ上書き（カンマ区切り）。
maxConcurrentRequests	integer	10	予約済み／将来の使用向け。
enableCaching	boolean	true	Figma からの GET レスポンスをキャッシュします。

ローカル／CLI 入力ファイルの例（apify run）：

{
  "figmaAccessToken": "figd_...",
  "port": 8080
}

HTTP API

メソッド	パス	説明
GET	/	サービス情報とエンドポイント一覧
GET	/health	稼働状態。auth_mode（pat | oauth | pending_oauth）、figma_authenticated を含みます
POST	/mcp	MCP JSON-RPC 2.0（このサーバーの主要なトランスポート）
GET	/oauth/authorize	OAuth を開始します（ブラウザー）。PAT が設定されている場合は無効です
GET	/oauth/callback	OAuth リダイレクトハンドラー

Apify MCP パス： .actor/actor.json では webServerMcpPath に /mcp が設定されています。通常、MCP クライアントの URL は次のとおりです。

https://<container-id>.runs.apify.net/mcp

（実行ページの Container URL に /mcp を追加してください。）

Cursor IDE

1. Actor をデプロイして起動し、実行中の Container URL をコピーします（ステータスが RUNNING の間）。
2. ~/.cursor/mcp.json を編集します（Windows/Linux ではパスが異なります。Cursor のドキュメントを参照してください）。

例（リモート HTTP MCP — お使いの Cursor バージョンで求められる形式に合わせて調整してください）：

{
  "mcpServers": {
    "figma-mcp-standby": {
      "url": "https://YOUR_RUN_ID.runs.apify.net/mcp"
    }
  }
}

注意事項

• mcp.json の env.APIFY_TOKEN はこの Node プロセスに渡されず、Figma 認証の代わりにはなりません。Actor の入力で figmaAccessToken（または OAuth）を使用してください。
• Container URL は実行ごとに異なり、実行が終了すると使えなくなります。新しい実行の後は mcp.json を更新し、Cursor を再起動してください。
• 接続に失敗した場合は、Cursor → Output → MCP と curl https://.../health を使用してください。

Claude Desktop / その他のクライアント

クライアントでサポートされている方法を使って、リモート MCP URL（例：https://.../mcp を指定する mcp-remote）を追加してください。パスとクエリパラメーターはクライアントのバージョンによって異なります。

ローカル開発

npm install
apify run

または、環境変数／入力を自分で注入して、Node でエントリを実行します。

export FIGMA_ACCESS_TOKEN="figd_..."
node src/main.js

ヘルス状態を確認します（ポートはログまたは入力で確認してください）。

curl -s http://localhost:8080/health | jq .

MCP 初期化の例：

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

プロジェクト構成

figma_mcp_actor/
├── .actor/
│   ├── actor.json           # Apify Actor metadata (incl. webServerMcpPath: /mcp)
│   ├── input_schema.json
│   ├── output_schema.json
│   └── dataset_schema.json
├── src/
│   ├── main.js              # Express app, /mcp, /oauth/*, Apify bootstrap
│   ├── figma/
│   │   ├── auth.js          # PAT + OAuth token exchange, refresh, KV hook
│   │   └── client.js        # Figma REST wrapper
│   ├── oauth/
│   │   └── persist.js       # Apify KV: FIGMA_OAUTH_SESSION
│   ├── mcp/                 # Protocol, handlers, server
│   ├── tools/
│   ├── resources/
│   └── prompts/
├── Dockerfile
├── package.json
└── README.md

MCP ツール（概要）

ファイル分析（analyze_file、get_file_structure、…）、コンポーネント（list_components、…）、エクスポート（export_node、…）、コメント（get_comments、create_comment、…）、デザイン変更ヘルパーに加え、リソース（figma://file/... など）や一般的なタスク向けのプロンプトが含まれます（名称はコード内で若干異なる場合があります）。

制限事項

• REST と Plugin API — 詳細なデザインの書き込みには Plugin API が必要になる場合があります。この Actor は、サポートされている範囲で REST を使用します。
• 一時的な Apify URL — 安定したホスティング方式を使用しない限り、実行ごとにベース URL が新しくなります。
• OAuth — 実行ごとに保存されるセッションは 1 つです（KV）。1 つのプロセスで複数ユーザーが同時に OAuth を利用することはできません。

スクリプト

npm run lint
npm run lint:fix
npm run format

ライセンス

ISC

変更履歴

0.2

• OAuth 2.0（Figma 認可コード + 更新）をオプションで利用可能。PAT が設定されている場合は、引き続きデフォルトで PAT が使用されます。
• /oauth/authorize と /oauth/callback を追加。セッションはデフォルトの KV（FIGMA_OAUTH_SESSION）に保持されます。
• 入力：oauthRedirectUri、oauthScopes。
• ヘルス JSON：auth_mode、figma_authenticated。

0.1 / 0.0.1

• MCP と Figma REST の初期連携、PAT、長時間稼働サーバー、/mcp JSON-RPC。

---

参考資料： Apify Actors · Figma REST API · Model Context Protocol