Figma MCP サーバー

Claude やその他の MCP 対応クライアントを介して Figma API との統合を実現する Model Context Protocol (MCP) サーバー。現在は Figma ファイルとプロジェクトへの読み取り専用アクセスをサポートしていますが、サーバーサイドアーキテクチャはより高度なデザイントークンとテーマ管理機能をサポート可能です（Figma API の拡張またはプラグインの開発を待っています）。

プロジェクトのステータス

現在の進捗状況

• ✅コア実装: モデルコンテキストプロトコル (MCP) に準拠した TypeScript サーバーの構築に成功しました
• ✅ Claude デスクトップ統合: Claude デスクトップでテスト済み、機能的
• ✅読み取り操作: Figma ファイルアクセス用のget-fileおよびlist-filesツールの動作
• ✅サーバーアーキテクチャ: キャッシュシステム、エラー処理、統計監視が実装されています
• ✅トランスポートプロトコル: stdio と SSE トランスポートメカニズムの両方をサポート

完全な機能の潜在

サーバーは、次の機能をサポートするコードを使用して設計されています (現在は API 制限によって制限されています)。

• 変数管理: デザイントークン(変数)の作成、読み取り、更新、削除
• 参照処理:トークン間の関係を作成し検証する
• テーマ管理: 複数のモード（例: 明るい/暗い）でテーマを作成します
• 依存関係分析: 循環参照を検出して防止する
• バッチ操作: 変数とテーマに対して一括操作を実行します

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

特徴

• 🔑 Figma API による安全な認証
• 📁 ファイル操作（読み取り、リスト）
• 🎨 デザインシステム管理
  • 変数の作成と管理
  • テーマの作成と設定
  • 参照処理と検証
• 🚀 パフォーマンスが最適化されました
  • LRUキャッシュ
  • レート制限の処理
  • 接続プール
• 📊 包括的な監視
  • 健康診断
  • 使用統計
  • エラー追跡

前提条件

• Node.js 18.x 以上
• 適切な権限を持つFigmaアクセストークン
• MCP（モデルコンテキストプロトコル）の基本的な理解

インストール

構成

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

2. Claude デスクトップ統合の場合:

サーバーは、Claude Desktop 構成ファイルで構成できます。

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

重要な注意事項:

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

使用法

基本的な使い方

利用可能なツール

1. ファイルを取得
   • Figmaファイルの詳細を取得するGXP5
2. リストファイル
   • FigmaプロジェクトGXP6内のファイルを一覧表示する
3. 変数の作成
   • デザインシステム変数GXP7の作成
4. テーマ作成
   • テーマの作成と設定 GXP8

APIドキュメント

サーバーメソッド

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

ツールスキーマ

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

エラー処理

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

• 無効なトークン: 特定のエラーメッセージを含む 403
• レート制限: リセット時間付き429
• 検証エラー: フィールド固有の詳細を含む 400
• サーバーエラー: エラー追跡付き 500

制限事項と既知の問題

API制限

1. 読み取り専用操作
   • Figma API の制限により読み取り専用操作に制限されます
   • 個人アクセストークンは読み取り操作のみをサポートし、書き込み操作はサポートしません。
   • 個人トークンを使用して REST API 経由で変数、コンポーネント、またはスタイルを変更することはできません
   • 書き込み操作には、代わりにFigmaプラグインの開発が必要になります。
2. レート制限
   • Figma API のレート制限に従います
   • より良い処理のために指数バックオフを実装する
3. キャッシュ管理
   • デフォルトの5分間のTTL
   • 500名限定
   • キャッシュ無効化フックの実装を検討する
4. 認証
   • 個人アクセストークンのみサポート
   • チームレベルの権限や共同編集はサポートされていません
   • 将来的にOAuth実装が予定されている
5. 技術的実装
   • 設定には絶対パスが必要です
   • 実行前にTypeScriptファイルをコンパイルする必要がある
   • ローカルとグローバルの両方のモジュール解決を処理する必要があります

貢献

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. テストで変更を加える
4. プルリクエストを送信する

弊社のコーディング標準に従ってください:

• TypeScript 厳密モード
• ESLintの設定
• テスト用のJest
• 包括的なエラー処理

ライセンス

MITライセンス - 詳細は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:コミュニティに参加する