YetAnotherFigmaMCP
by yk-lab
README.md
# YetAnotherFigmaMCP
[](https://github.com/yk-lab/yet-another-figma-mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/yk-lab/yet-another-figma-mcp)
[](https://qlty.sh/gh/yk-lab/projects/yet-another-figma-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://github.com/microsoft/pyright)
[](https://deepwiki.com/yk-lab/yet-another-figma-mcp)
Figma ファイルをローカルキャッシュし、MCP (Model Context Protocol) サーバーとして提供する軽量ツール。
## 背景
Figma 無料プランでは API / MCP 呼び出し回数が月 6 回までに制限されています。本ツールは Figma のファイル・ノード JSON を事前取得しキャッシュすることで、この制限内で効率的にデザインデータを活用できるようにします。
## 特徴
- **事前キャッシュ方式**: Figma API を事前に叩いて JSON をローカル保存
- **検索用インデックス**: ノード名・フレーム名での高速検索
- **MCP サーバー**: AI エージェントからキャッシュデータを参照可能
- **API 呼び出し最小化**: キャッシュ生成時と明示的リフレッシュ時のみ API 使用
## インストール
```bash
pip install yet-another-figma-mcp
```
または uvx / pipx でも利用可能:
```bash
uvx yet-another-figma-mcp --help
pipx install yet-another-figma-mcp
```
## セットアップ
### Figma API トークンの設定
環境変数に Figma API トークンを設定:
```bash
export FIGMA_API_TOKEN="your-figma-api-token"
```
トークンは [Figma の設定画面](https://www.figma.com/developers/api#access-tokens) から取得できます。
## 使い方
### キャッシュの生成
```bash
# 単一ファイルのキャッシュ生成
yet-another-figma-mcp cache --file-id <FILE_ID>
# 複数ファイル
yet-another-figma-mcp cache --file-id <ID1> --file-id <ID2>
# ファイル ID リストから一括生成
yet-another-figma-mcp cache --file-id-list path/to/file_ids.txt
# 強制リフレッシュ（API を再度呼び出し）
yet-another-figma-mcp cache --file-id <FILE_ID> --refresh
```
### MCP サーバーの起動
```bash
# MCP サーバー起動
yet-another-figma-mcp serve
# 動作確認
yet-another-figma-mcp status
```
### Claude Desktop での設定
`claude_desktop_config.json` に以下を追加:
```json
{
"mcpServers": {
"figma-cache": {
"command": "uvx",
"args": ["yet-another-figma-mcp", "serve"]
}
}
}
```
## MCP ツール一覧
MCP サーバーは以下のツールを提供します:
### `get_cached_figma_file`
指定ファイルのノードツリーやメタデータを取得。
```
引数:
- file_id: string (必須)
返り値:
- ルートノードと主要フレーム一覧
- ファイル全体のメタデータ
```
### `get_cached_figma_node`
単一ノードの詳細情報を取得。
```
引数:
- file_id: string (必須)
- node_id: string (必須)
返り値:
- ノードのプロパティ（type, name, layout, style, children など）
```
### `search_figma_nodes_by_name`
ノード名でノードを検索。
```
引数:
- file_id: string (必須)
- name: string (必須)
- match_mode: "exact" | "partial" (オプション、デフォルト: exact)
- limit: number (オプション)
返り値:
- マッチしたノードのリスト
```
### `search_figma_frames_by_title`
フレーム名からフレームノードを検索。
```
引数:
- file_id: string (必須)
- title: string (必須)
- match_mode: "exact" | "partial" (オプション)
- limit: number (オプション)
返り値:
- 対象フレームノードの一覧
```
### `list_figma_frames`
ファイル直下の主要フレーム一覧を取得。
```
引数:
- file_id: string (必須)
返り値:
- フレーム名・node_id・パスのリスト
```
## キャッシュファイルの構造
```
~/.yet_another_figma_mcp/
index.json # 全ファイル共通のメタ情報
<file_id>/
file_raw.json # Figma API /files の生 JSON
nodes_index.json # ノード検索用インデックス
```
## ユースケース例
### 画面実装の参照
```
ユーザー: 「サインアップ画面を実装してください」
→ AI: search_figma_frames_by_title で「Sign Up」を検索
→ AI: get_cached_figma_node でフレーム構造を取得
→ AI: 取得したデザイン情報をもとにコード生成
```
### コンポーネントの特定
```
ユーザー: 「Primary Button のスタイルを教えて」
→ AI: search_figma_nodes_by_name で検索
→ AI: get_cached_figma_node で詳細取得
```
## 制限事項
本ツールは PoC（Proof of Concept）として以下の機能はスコープ外としています:
- スクリーンショット取得
- Code Connect（ノード⇔コンポーネント対応）
- 変数・デザイントークンの取得
- FigJam 対応
## 開発
### セットアップ
```bash
# 開発用依存関係をインストール
uv sync --group dev
```
### Task コマンド（推奨）
[Task](https://taskfile.dev/) がインストールされている場合、以下のコマンドが使えます:
```bash
# 利用可能なタスク一覧
task
# 依存関係インストール
task install
# リント
task lint
# リント（自動修正付き）
task lint:fix
# フォーマット
task format
# フォーマット確認（修正なし）
task format:check
# 型チェック
task typecheck
# テスト
task test
# テスト（詳細出力）
task test:verbose
# テスト（並列実行）
task test:parallel
# テスト（カバレッジ付き）
task test:cov
# 全チェック（lint + format:check + typecheck + test）
task check
# pre-commit フック実行
task pre-commit
# MCP サーバー起動
task serve
# MCP サーバー起動（詳細ログ付き）
task serve:verbose
# キャッシュ状態確認
task status
# Figma ファイルをキャッシュ
task cache -- -f <FILE_ID>
# 生成ファイルのクリーンアップ
task clean
```
### 手動実行
```bash
# リント
uv run ruff check .
# フォーマット
uv run ruff format .
# 型チェック
uv run pyright
# テスト
uv run pytest
```
## Acknowledgments
- [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) - AI 向けノード簡略化のアプローチを参考にさせていただきました
## ライセンス
MIT License - 詳細は [LICENSE](LICENSE) を参照してください。
TDQS
A3.9/5.0
Scored across 5 tools
Disambiguation4/5
Tools are mostly distinct, but list_figma_frames and get_cached_figma_file both return frame lists, which could cause confusion. Search nodes by name and search frames by title also overlap, though descriptions clarify the scope difference.
Naming Consistency5/5
All tools follow a consistent <verb>_figma_<resource> pattern, using get for single resources, search/list for plural collections, and qualifiers like by_name or by_title for searches. This makes the set predictable and easy to navigate.
Tool Count5/5
Five tools is a well-scoped size for a read-only Figma caching server, covering file metadata, frame enumeration, node search, and node detail retrieval without unnecessary bloat.
Completeness4/5
The toolkit covers the core exploration workflow: get file → list frames → search nodes → get node details. Minor gaps exist, such as no direct asset export or style querying, but the stated purpose is served without dead ends.
Maintenance
ActivityInactive
ResponsivenessUnresponsive