custom-figma-mcp

軽量なローカル MCP (Model Context Protocol) サーバーは、Figmaのホスト型/リモートMCP統合を必要とせずに、AIコーディングエージェント（OpenCodeなど）に、Figmaファイルへの構造化された読み取り専用アクセス（ファイル階層、ノードプロパティ、レンダリング画像）を提供します。

なぜこれが存在するのか

Figmaの公式リモートMCPサーバーは、許可リストに登録されたClient IDの背後にゲートされており、独自のエージェントツールを構築しようとしている個人開発者にとっては実用的ではありません。このプロジェクトは、個人アクセストークンを使ってFigmaの公開REST APIに直接通信し、stdioを介した標準のMCPツールインターフェースを通してエージェントに公開することで、その障壁を回避します。

Related MCP server: figma-mcp

アーキテクチャ

OpenCode (MCP client)
      │  stdio (JSON-RPC)
      ▼
custom-figma-mcp (this server)
      │  HTTPS + X-Figma-Token
      ▼
Figma REST API (api.figma.com/v1)

このサーバーは単一のNode.jsプロセスであり、以下のことを行います：

1. @modelcontextprotocol/sdkを使用してstdio経由で起動し、自身を登録します。

2. ListToolsRequestSchemaを介して、MCPクライアント（OpenCode）に固定のツールセットをアドバタイズします。

3. CallToolRequestSchemaを介してツール呼び出しを実行し、個人アクセストークンをヘッダーとして添付してFigmaのREST APIにプロキシします。

4. 構造化されたJSON（または画像URL）を呼び出し元のエージェントに返します。

読み取り専用スコープのトークンを持つGETリクエストのみを使用するため、Figma内のあらゆるものを変更、コメント、削除することはできません。設計上、厳密に読み取り専用です。

公開されるツール

get_figma_file_structure

ファイルのページ/フレーム階層を返します。大規模ファイルではノードツリー全体が数万ノードに及ぶことがあるため、ダンプしないように深さが制限されています。

入力：

{ "fileKey": "string", "depth": 2 }

対応先： GET /v1/files/:fileKey?depth=:depth

get_figma_node_details

特定のノードIDの完全なプロパティを取得します。オートレイアウト設定、パディング/ギャップ値、塗り、ストローク、タイポグラフィ、制約、コンポーネントプロパティなどです。これは正確なコード生成に使用される主要なツールです。

入力：

{ "fileKey": "string", "nodeIds": ["1:2", "104:15"] }

対応先： GET /v1/files/:fileKey/nodes?ids=1:2,104:15

get_figma_node_image

特定のノードをPNGとしてレンダリングし、一時的な署名付きURLを返します。生成したコードをデザインと視覚的に照合するのに役立ちます。

入力：

{ "fileKey": "string", "nodeId": "104:15", "scale": 2 }

対応先： GET /v1/images/:fileKey?ids=104:15&scale=2

3つのツールに分けている理由（1つにしない理由）

Figmaファイルは巨大になることがあります。深さ制限なしのGET /files/:key呼び出し1回で、深くネストされた数メガバイトのJSONが返り、LLMのコンテキストウィンドウを瞬時に使い果たしてしまいます。インターフェースを3つの特化したツールに分けることで、エージェントは以下のことができます：

1. まず軽量のアウトライン（get_figma_file_structure）を取得して、関連するフレーム/ノードを特定します。

2. 必要な特定のノードにだけ詳しく入ります（get_figma_node_details）。

3. 視覚的確認が必要な時だけ、オプションで画像をレンダリングします（get_figma_node_image）。

これは、人間の開発者がデザインを検査する方法（まず全体をざっと見て、それから拡大する）を反映しています。ファイル全体を一度に取り込むのではありません。

認証

認証には、file_content:readにスコープされたFigmaの個人アクセストークン（PAT）を使用します。トークンはローカルの.envファイルから読み込まれ（ハードコードはされません）、すべての送信リクエストにX-Figma-Tokenヘッダーとして添付されます。トークンがローカルマシンを離れるのは、api.figma.comへの直接リクエストのみです。

エラー処理

すべてのツールハンドラーはtry/catchでラップされています。失敗時（無効なファイルキー、アクセス権なし、レート制限など）には、サーバーはMCP準拠のエラーレスポンスを返します：

{
  "content": [{ "type": "text", "text": "Figma API Error: <details>" }],
  "isError": true
}

これにより、呼び出し元のエージェントは、黙ってクラッシュする代わりに、実際の失敗理由を確認できます。

プロジェクト構成

custom-figma-mcp/
├── index.js        # server entrypoint — tool definitions + handlers
├── package.json    # dependencies, "type": "module" for ESM imports
├── .env            # local only — holds FIGMA_PAT, never committed
└── .gitignore

ローカル開発

デバッグのためにサーバーを直接実行します（stdioを介して通信するため、通常のHTTPサーバーログは表示されません）：

node index.js

実際にはこれを手動で実行することはありません。OpenCodeがopencode.jsonで定義されたcommandに基づいて、サブプロセスとして起動します。

このサーバーを拡張する

1. ListToolsRequestSchemaが返すtools配列にスキーマを追加します。

2. CallToolRequestSchemaハンドラー内に、一致するif (name === "...")分岐を追加します。

3. ベースURLと認証ヘッダーが事前設定されたaxiosインスタンスであるfigmaApiの下で、関連するFigma RESTエンドポイントにマッピングします。

新しいツールは読み取り専用かつスコープを限定したままにしてください。エージェントのコンテキスト使用量を低く抑えるため、可能な限りフィルタリングされていない完全なAPIレスポンスをダンプすることは避けてください。