figma-mcp-cached

# Figma MCP Cached > Skill by [ara.so](https://ara.so) — Design Skills collection. A cache-enabled Figma Context MCP (Model Context Protocol) server that uses persistent disk caching to dramatically reduce Figma API requests, mitigate rate limiting issues, and improve response times. Built on TypeScript, this MCP server is optimized for AI coding agents in Cursor, Claude Desktop, and other MCP-compatible clients. ## What It Does - **Persistent Disk Caching**: Stores Figma API responses locally with configurable TTL (time-to-live) - **Rate Limit Mitigation**: Reduces API calls by 10x+ after initial cache, perfect for free Figma accounts - **Smart File Preparation**: `figma_prepare_file` tool validates cache, checks nodeIds, and auto-refreshes when needed - **Force Refresh**: Override cache to fetch latest design updates on demand - **LRU Memory Cache**: In-memory caching layer to avoid repeated disk I/O - **Optional Encryption**: AES-256-CBC encryption for sensitive design data - **Auto Cleanup**: Scheduled cleanup of expired cache files - **System Integration**: Saves downloaded images to OS-specific Downloads folder by default ## Installation ### For MCP Clients (Cursor, Claude Desktop, etc.) Add to your MCP configuration file (e.g., `~/.cursor/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "figma-mcp-cached": { "command": "npx", "args": [ "-y", "@pactortester/figma-mcp-cached", "--stdio", "--figma-api-key=${FIGMA_API_KEY}", "--figma-caching={\"ttl\":{\"value\":7,\"unit\":\"d\"}}" ] } } } ``` ### Get Figma API Key 1. Visit [Figma Developer Settings](https://www.figma.com/developers/api#access-tokens) 2. Create a Personal Access Token 3. Set environment variable: `export FIGMA_API_KEY=your_token_here` ### Verify Installation Restart your MCP client and check that the `figma-mcp-cached` server appears in the tools list with three tools: - `figma_prepare_file` - `get_figma_data` - `download_figma_images` ## Configuration Options ### Basic Configuration ```json { "mcpServers": { "figma-mcp-cached": { "command": "npx", "args": [ "-y", "@pactortester/figma-mcp-cached", "--stdio", "--figma-api-key=${FIGMA_API_KEY}", "--figma-caching={\"ttl\":{\"value\":30,\"unit\":\"d\"}}" ] } } } ``` ### Full Configuration with All Options ```json { "mcpServers": { "figma-mcp-cached": { "command": "npx", "args": [ "-y", "@pactortester/figma-mcp-cached", "--stdio", "--figma-api-key=${FIGMA_API_KEY}", "--figma-caching={\"ttl\":{\"value\":30,\"unit\":\"d\"},\"cacheDir\":\"~/figma-cache\",\"autoCleanup\":true,\"cleanupInterval\":{\"value\":1,\"unit\":\"h\"},\"maxMemoryCacheSize\":200,\"encryptionKey\":\"${FIGMA_CACHE_ENCRYPTION_KEY}\"}" ] } } } ``` ### Configuration Parameters #### `ttl` (Required) Cache time-to-live. Units: `ms`, `s`, `m`, `h`, `d` ```json {"ttl": {"value": 7, "unit": "d"}} // 7 days {"ttl": {"value": 2, "unit": "h"}} // 2 hours ``` #### `cacheDir` (Optional) Custom cache directory. Defaults: - **Linux**: `~/.cache/figma-mcp` - **macOS**: `~/Library/Caches/FigmaMcp` - **Windows**: `%LOCALAPPDATA%/FigmaMcpCache` ```json {"cacheDir": "~/my-figma-cache"} ``` #### `autoCleanup` (Optional) Enable automatic cleanup of expired cache. Default: `true` ```json {"autoCleanup": true} ``` #### `cleanupInterval` (Optional) Auto-cleanup frequency. Default: 1 hour ```json {"cleanupInterval": {"value": 1, "unit": "h"}} ``` #### `maxMemoryCacheSize` (Optional) Max LRU memory cache entries. Default: `100` ```json {"maxMemoryCacheSize": 200} ``` #### `encryptionKey` (Optional) AES-256-CBC encryption key for cache files. Use for sensitive designs. ```json {"encryptionKey": "${FIGMA_CACHE_ENCRYPTION_KEY}"} ``` ## MCP Tools Reference ### 1. figma_prepare_file **Purpose**: Prepare and validate Figma file cache before fetching data. This tool should ALWAYS be called before `get_figma_data`. **Parameters**: ```typescript { figmaUrl: string; // Full Figma URL forceRefresh?: boolean; // Force fresh API fetch, bypass cache } ``` **Usage Pattern**: ```typescript // Step 1: Prepare file (LLM does this automatically) await figma_prepare_file({ figmaUrl: "https://www.figma.com/design/QlQwKAl9abcdhvlfvpM5K/Design?node-id=2777-9428" }); // Step 2: Get data (LLM does this next) await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodeId: "2777-9428" }); ``` **Force Refresh Example**: ```typescript // User says: "Get me the latest design updates" await figma_prepare_file({ figmaUrl: "https://www.figma.com/design/QlQwKAl9abcdhvlfvpM5K/Design", forceRefresh: true // Bypass cache, fetch from API }); ``` **Return Values**: - Cache exists & valid → "File is ready, cache is fresh" - Cache expired or missing → Fetches from API, caches, returns "File prepared and cached" - Force refresh → Always fetches from API, updates cache - NodeId not found → Re-fetches and validates ### 2. get_figma_data **Purpose**: Retrieve Figma design data with layout, styles, components, and content. **Parameters**: ```typescript { fileKey: string; // Figma file key from URL nodeId?: string; // Optional node ID (format: "1234:5678" or "1234-5678") depth?: number; // Optional traversal depth (omit unless user specifies) } ``` **Usage Examples**: ```typescript // Get entire file const result = await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K" }); // Get specific node const result = await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodeId: "2777-9428" }); // Limit traversal depth (rare, only if user asks) const result = await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodeId: "2777-9428", depth: 3 }); ``` **Return Structure**: ```typescript { metadata: { name: string; lastModified: string; version: string; }; nodes: { // Node tree with layout, styles, text, etc. }; globalVars: { // Reusable styles extracted as variables }; components: { // Component definitions }; componentSets: { // Component set definitions }; } ``` ### 3. download_figma_images **Purpose**: Download SVG and PNG images from Figma nodes. **Parameters**: ```typescript { fileKey: string; // Figma file key nodes: Array<{ nodeId: string; // Node ID fileName: string; // Output filename (.png or .svg) imageRef?: string; // Image fill reference ID (required for image fills) needsCropping?: boolean; // Apply crop transform cropTransform?: number[]; // Figma transform matrix requiresImageDimensions?: boolean; // Return dimensions for CSS }>; localPath?: string; // Save directory (default: OS Downloads folder) pngScale?: number; // PNG export scale (default: 2) } ``` **Usage Examples**: ```typescript // Download to default Downloads folder const result = await download_figma_images({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodes: [ { nodeId: "2777-9428", fileName: "hero-image.png" }, { nodeId: "2777-9430", fileName: "icon-star.svg" } ], pngScale: 2 // 2x resolution }); // Download to custom path const result = await download_figma_images({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodes: [ { nodeId: "2777-9428", fileName: "hero.png", requiresImageDimensions: true // Get width/height for CSS } ], localPath: "/Users/dev/project/assets", pngScale: 3 }); // Download image with cropping const result = await download_figma_images({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodes: [ { nodeId: "2777-9428", fileName: "cropped-image.png", imageRef: "abc123ref", needsCropping: true, cropTransform: [1, 0, 0, 1, 0, 0] } ] }); ``` **Return Structure**: ```typescript { downloadedCount: number; savedTo: string; images: Array<{ fileName: string; width?: number; height?: number; cropped?: boolean; }>; } ``` ### 4. list_cache (Bonus Tool) View current cache status and statistics. ```typescript await list_cache(); // Returns: { enabled, cacheDir, ttl, files, totalSize } ``` ### 5. cleanup_cache (Bonus Tool) Manually clean up expired and corrupted cache files. ```typescript await cleanup_cache(); // Returns: { removed, freedSpace } ``` ## Common Workflows ### Workflow 1: First-Time Design Fetch ```typescript // User provides Figma URL const url = "https://www.figma.com/design/QlQwKAl9abcdhvlfvpM5K/MyDesign?node-id=2777-9428"; // Step 1: AI calls figma_prepare_file await figma_prepare_file({ figmaUrl: url }); // → Fetches from API, caches locally // Step 2: AI calls get_figma_data const data = await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodeId: "2777-9428" }); // → Returns cached data ``` ### Workflow 2: Cached Design Fetch (10x+ faster) ```typescript // Same URL, within cache TTL const url = "https://www.figma.com/design/QlQwKAl9abcdhvlfvpM5K/MyDesign?node-id=2777-9428"; // Step 1: AI calls figma_prepare_file await figma_prepare_file({ figmaUrl: url }); // → Cache valid, skips API call // Step 2: AI calls get_figma_data const data = await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K", nodeId: "2777-9428" }); // → Returns from cache (disk or memory), no API call ``` ### Workflow 3: Force Refresh After Design Update ```typescript // User says: "The design was just updated, get the latest" const url = "https://www.figma.com/design/QlQwKAl9abcdhvlfvpM5K/MyDesign"; // AI calls with forceRefresh await figma_prepare_file({ figmaUrl: url, forceRefresh: true // Bypass cache }); const data = await get_figma_data({ fileKey: "QlQwKAl9abcdhvlfvpM5K" }); // → Fresh data from API, cache updated ```