Figma MCP Server

Figma MCP Server

Claude やその他の MCP 互換クライアントを通じて、Figma の API と連携する Model Context Protocol（MCP）サーバーです。現在、Figma のファイルとプロジェクトへの読み取り専用アクセスに対応しています。サーバー側のアーキテクチャは、より高度なデザイントークンやテーマ管理機能をサポートできるよう設計されています（Figma API の機能拡張またはプラグインの開発待ちです）。

プロジェクトの状況

現在の進捗

• ✅ コア実装：Model Context Protocol（MCP）に準拠した TypeScript サーバーの構築に成功しました
• ✅ Claude Desktop との統合：Claude Desktop でテスト済みで、正常に動作します
• ✅ 読み取り操作：Figma ファイルへのアクセスに使う get-file ツールと list-files ツールが動作します
• ✅ サーバーアーキテクチャ：キャッシュシステム、エラー処理、統計情報の監視を実装しました
• ✅ トランスポートプロトコル：stdio と SSE の両方のトランスポート方式に対応しています

将来的に可能な機能

サーバーには、以下の機能をサポートするコードが用意されています（現在は API の制限により利用が制限されています）。

• 変数管理：デザイントークン（変数）の作成、読み取り、更新、削除
• 参照の処理：トークン間の関連付けの作成と検証
• テーマ管理：複数のモード（ライト／ダークなど）を持つテーマの作成
• 依存関係の分析：循環参照の検出と防止
• 一括操作：変数やテーマに対する一括操作

Figma プラグインの開発、または API アクセスの拡張により、これらの機能をすべて有効にできます。

機能

• 🔑 Figma API による安全な認証
• 📁 ファイル操作（読み取り、一覧表示）
• 🎨 デザインシステムの管理
  • 変数の作成と管理
  • テーマの作成と設定
  • 参照の処理と検証
• 🚀 パフォーマンスの最適化
  • LRU キャッシュ
  • レート制限の処理
  • コネクションプーリング
• 📊 包括的な監視
  • ヘルスチェック
  • 使用統計
  • エラー追跡

前提条件

• Node.js 18.x 以降
• 適切な権限を持つ Figma アクセストークン
• MCP（Model Context Protocol）の基本的な理解

インストール

npm install figma-mcp-server

設定

1. .env.example を基に .env ファイルを作成します。

# Figma API Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
DEBUG=figma-mcp:*

2. Claude Desktop との統合の場合：

サーバーは、Claude Desktop の設定ファイルで設定できます。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-mcp-server/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

重要な注意事項：

• 相対パスではなく、絶対パスを使用してください
• Windows では、パスに二重のバックスラッシュ（\\）を使用してください
• 設定を変更した後は、Claude Desktop を再起動してください

使用方法

基本的な使用方法

import { startServer } from 'figma-mcp-server';

const server = await startServer(process.env.FIGMA_ACCESS_TOKEN);

利用可能なツール

1. get-file

   • Figma ファイルの詳細を取得します

   {
     "name": "get-file",
     "arguments": {
       "fileKey": "your_file_key"
     }
   }
   

2. list-files

   • Figma プロジェクト内のファイルを一覧表示します

   {
     "name": "list-files",
     "arguments": {
       "projectId": "your_project_id"
     }
   }
   

3. create-variables

   • デザインシステムの変数を作成します

   {
     "name": "create-variables",
     "arguments": {
       "fileKey": "your_file_key",
       "variables": [
         {
           "name": "primary-color",
           "type": "COLOR",
           "value": "#0066FF"
         }
       ]
     }
   }
   

4. create-theme

   • テーマを作成して設定します

   {
     "name": "create-theme",
     "arguments": {
       "fileKey": "your_file_key",
       "name": "Dark Theme",
       "modes": [
         {
           "name": "dark",
           "variables": [
             {
               "variableId": "123",
               "value": "#000000"
             }
           ]
         }
       ]
     }
   }
   

API ドキュメント

サーバーメソッド

• startServer(figmaToken: string, debug?: boolean, port?: number)
  • MCP サーバーを初期化して起動します
  • 戻り値：Promise

ツールのスキーマ

すべてのツール入力は、Zod スキーマを使用して検証されます。

const CreateVariablesSchema = z.object({
  fileKey: z.string(),
  variables: z.array(z.object({
    name: z.string(),
    type: z.enum(['COLOR', 'FLOAT', 'STRING']),
    value: z.string(),
    scope: z.enum(['LOCAL', 'ALL_FRAMES'])
  }))
});

エラー処理

サーバーは詳細なエラーメッセージと適切なエラーコードを提供します。

• 無効なトークン：403 と具体的なエラーメッセージ
• レート制限：429 とリセット時刻
• 検証エラー：400 とフィールドごとの詳細
• サーバーエラー：500 とエラー追跡

制限事項と既知の問題

API の制限事項

1. 読み取り専用操作

   • Figma API の制限により、読み取り専用操作に限定されています
   • パーソナルアクセストークンは読み取り操作のみをサポートし、書き込み操作はサポートしません
   • パーソナルトークンを使用して REST API 経由で変数、コンポーネント、スタイルを変更することはできません
   • 書き込み操作には、代わりに Figma プラグインの開発が必要です

2. レート制限

   • Figma API のレート制限に従います
   • より適切に処理するため、指数バックオフを実装してください

3. キャッシュ管理

   • デフォルトの TTL は 5 分です
   • 最大 500 件です
   • キャッシュ無効化フックの実装を検討してください

4. 認証

   • パーソナルアクセストークンのみをサポートします
   • チームレベルの権限や共同編集はサポートしていません
   • OAuth の実装は今後の予定です

5. 技術的な実装

   • 設定には絶対パスが必要です
   • 実行前に TypeScript ファイルをコンパイルする必要があります
   • ローカルとグローバルの両方のモジュール解決に対応する必要があります

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. テストを追加して変更を行います
4. プルリクエストを送信します

コーディング規約に従ってください：

• TypeScript の strict モード
• ESLint の設定
• テストには Jest を使用
• 包括的なエラー処理

ライセンス

MIT License - 詳細については LICENSE ファイルを参照してください

トラブルシューティング

包括的なトラブルシューティングガイドについては、TROUBLESHOOTING.md を参照してください。

よくある問題

1. JSON 接続エラー

   • Claude Desktop の設定では絶対パスを使用してください
   • サーバーがビルドされていることを確認してください（npm run build）
   • すべての環境変数が設定されていることを確認してください

2. 認証の問題

   • Figma アクセストークンが有効であることを確認してください
   • トークンに必要な権限があることを確認してください
   • トークンが設定に正しく設定されていることを確認してください

3. サーバーが起動しない

   • Node.js のバージョンを確認してください（18.x+ が必要です）
   • ビルド成果物が存在することを確認してください（dist/index.js）
   • Claude Desktop のログを確認してください：
     • macOS：~/Library/Logs/Claude/mcp*.log
     • Windows：%APPDATA%\Claude\logs\mcp*.log

より詳しいデバッグ手順と解決策については、トラブルシューティングガイドを参照してください。

サポート

• GitHub Issues：バグを報告
• ドキュメント：Wiki
• Discord：コミュニティに参加