Figma Cache Design MCP
Integrates with the Figma REST API to cache designs locally and provide compact page outlines, block-level CSS-like layout trees, and design token summaries for AI coding agents, with optional cache refresh and cleanup.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
figma-cache-design-mcp
Cache-first Model Context Protocol (MCP) server that delivers compact, CSS-like Figma block designs and page outlines from a persistent local disk cache, calling the Figma REST API only on a cache miss or when explicitly refreshed.
Designed specifically for AI coding agents to minimize LLM token consumption, avoid Figma API rate limits, and streamline frontend implementation.
Quick Start & MCP Client Configuration
No manual git clone or repository building is required. You can run figma-cache-design-mcp directly via npx in any MCP client (Claude Desktop, Cursor, Antigravity, Cline, Windsurf, etc.).
1. Configuration (npx)
Add figma-cache-design-mcp to your MCP client configuration file:
{
"mcpServers": {
"figma-cache-design-mcp": {
"command": "npx",
"args": ["-y", "figma-cache-design-mcp"],
"env": {
"FIGMA_TOKEN": "figd_your_personal_access_token",
"FIGMA_CACHE_DIR": "/absolute/path/to/cache/directory",
"FIGMA_CACHE_AUTO_CLEANUP": "true",
"FIGMA_CACHE_TTL": "30d"
}
}
}
}2. Environment Variables
FIGMA_TOKEN(required for Figma API requests) — Personal Access Token from Figma (Settings ➔ Security ➔ Personal access tokens).FIGMA_CACHE_DIR(required) — Absolute directory path for the local disk cache.FIGMA_CACHE_AUTO_CLEANUP(optional, default:false) — Set to"true"to automatically delete files older than TTL. Iffalse, files are never deleted automatically.FIGMA_CACHE_TTL(optional, default: stored forever) — Time to live / retention period. Supported units:s(seconds),m(minutes),h(hours),d(days). Examples:"30d","12h","45m","60s", or JSON'{"value": 30, "unit": "d"}'. By default, files are stored forever.
Related MCP server: Figma-Context-MCP-Cached
How to Use
A. MCP Tools (Inside Agent / Chat)
All link-based tools accept parameters in any combination (at least one of desktop, mobile, url, or urls is required):
desktop?: string— Figma link to the desktop version (page or block) withnode-id.mobile?: string— Figma link to the mobile version (page or block) withnode-id.url?: string— Single Figma link without a viewport label.urls?: string[]— Multiple Figma links at once (pages, sections, or individual blocks).refresh?: boolean— Force refresh from Figma API, bypassing disk cache (falseby default).
1. cache_design
Downloads one or more Figma designs (whole pages or individual blocks/parts) and saves them to the local disk cache without dumping large CSS trees into the chat context. Once cached, get_outline and get_block can work with them (and any nested child elements) completely offline without making Figma API calls.
2. get_outline
Downloads a whole page or section into cache and returns a compact outline of top-level frames/blocks with their IDs, names, dimensions (W×H), and ready-to-use links for get_block.
3. get_block
Returns an aggregated Design Tokens Summary (colors, typography, spacing, radii, shadows) and a compact CSS-like Layout Tree for the block. If its parent page or section was already cached via cache_design or get_outline, the block is extracted directly from the local cache with zero API calls.
4. list_cache
Lists all designs currently stored in the local MCP disk cache (fileKey?: string optional filter) along with node IDs, dimensions, timestamps, and ready-to-use URLs.
5. clean_cache
Cleans up expired Figma designs from disk cache based on configured TTL (force?: boolean to remove all files, fileKey?: string to target a specific file).
B. CLI Usage (Pre-caching from Terminal via npx)
You can pre-populate, inspect, or clean the local disk cache directly from your terminal using npx:
# Pre-cache desktop and mobile designs
npx -y figma-cache-design-mcp cache --desktop "https://www.figma.com/design/<fileKey>/...?node-id=0-1" --mobile "https://www.figma.com/design/<fileKey>/...?node-id=99-100"
# Pre-cache multiple blocks or pages at once
npx -y figma-cache-design-mcp cache "https://www.figma.com/design/<fileKey>/...?node-id=10-100" "https://www.figma.com/design/<fileKey>/...?node-id=20-200"
# Force refresh from Figma API
npx -y figma-cache-design-mcp cache --refresh "https://www.figma.com/design/<fileKey>/...?node-id=10-100"
# List all designs currently cached on disk
npx -y figma-cache-design-mcp list
# Clean expired cache files based on TTL
npx -y figma-cache-design-mcp clean
# Force-clean all cached files
npx -y figma-cache-design-mcp clean --force(Note: ensure FIGMA_TOKEN and FIGMA_CACHE_DIR environment variables are exported in your terminal session when running CLI commands).
Cache Retention & Auto-Cleanup (TTL)
figma-cache-design-mcp includes an automated cache lifecycle management system to control disk usage and ensure designs stay fresh:
1. Default Behavior
autoCleanup:false— Cache files are never deleted automatically.ttl:undefined— Cache files are kept forever and never expire unless refreshed or manually deleted.
2. Enabling Auto-Cleanup & TTL
When autoCleanup: true and ttl are configured:
On Reads (
get_block,get_outline): If a cached file is older than the configured TTL, it is immediately deleted from disk and treated as a cache miss, prompting a fresh fetch from Figma API.On Listing / Cleanup: Scans the cache directory, unlinks any expired JSON files, and removes empty project folders.
Supported Units:
s— seconds (e.g.,"60s")m— minutes (e.g.,"15m")h— hours (e.g.,"12h")d— days (e.g.,"30d")
3. Configuration Examples
In MCP Client configuration (env):
{
"env": {
"FIGMA_TOKEN": "figd_...",
"FIGMA_CACHE_DIR": "/path/to/cache",
"FIGMA_CACHE_AUTO_CLEANUP": "true",
"FIGMA_CACHE_TTL": "30d"
}
}(Also accepts JSON format: "FIGMA_CACHE_TTL": "{\"value\": 30, \"unit\": \"d\"}")
In TypeScript / Node.js API:
import { CacheManager } from "figma-cache-design-mcp";
const cache = new CacheManager({
cacheDir: "/path/to/cache",
autoCleanup: true,
ttl: { value: 30, unit: "d" }
});Why Use figma-cache-design-mcp Over the Official Figma MCP?
The official Figma MCP (and standard Figma REST API) was designed for design editors, returning raw, deeply nested scene graphs packed with transformation matrices, bezier curve coordinates, plugin metadata, and internal flags. While comprehensive, this raw format is poorly suited for LLM coding agents.
figma-cache-design-mcp is purpose-built for frontend development with AI agents:
Massive Context & Token Savings (up to 90–95% reduction):
Official MCP: Returning raw JSON for a medium-to-large page or frame can consume 50k–500k+ tokens, rapidly exhausting the LLM context window and degrading reasoning quality.
figma-cache-design-mcp: Strips away graphical boilerplate and translates the node tree into an aggregated Design Tokens Summary and a concise, indented CSS-like Layout Tree.
Subtree Cache-First Architecture (Zero API calls for cached elements):
Official MCP: Makes live network calls to Figma on every tool invocation.
figma-cache-design-mcp: Caching a page or section (via
cache_designorget_outline) allows any child button, card, or section to be resolved immediately from local disk via recursive subtree lookup — requiring 0 additional API requests and 0 network latency.
Protection Against Figma API Rate Limits (
429 Too Many Requests):An autonomous agent can run dozens of inspection steps in a loop. By caching once on disk (
FIGMA_CACHE_DIR), you avoid triggering Figma API tier limits.Built-in exponential backoff and auto-retry honoring the
Retry-Afterheader automatically recovers from transient rate spikes.
Transparent Diagnostic Logging:
Real-time
stderrlogs clearly indicateCache HIT (direct),Cache HIT (subtree), orCache MISS(displaying existing cached nodes in the file) so you always know why a request went to the network.
Intelligent Vector & Icon Collapsing:
SVG icons in Figma often contain dozens of nested
<VECTOR>nodes and boolean operations. This MCP automatically collapses them into a single[ICON/SVG "IconName" (24×24) { color: #... }]line, eliminating hundreds of lines of vector noise.
Native Multi-Viewport (Desktop + Mobile) in One Call:
Inspect both desktop and mobile layouts side-by-side in a single tool call to implement clean responsive styles without switching contexts.
Pre-Caching & Offline Support via CLI:
Pre-populate the cache from your terminal before starting an agent session (
npm run cache). The agent can then work completely offline or without consuming Figma API quotas.
Comparison Summary
Capability | Official Figma MCP | figma-cache-design-mcp |
Output Format | Raw multi-megabyte JSON | Compact CSS-like Tree + Design Tokens |
LLM Token Footprint | Extremely heavy (10k–100k+ tokens) | Minimal (only relevant CSS layout properties) |
Caching Model | None / ephemeral in-memory | Persistent disk cache + recursive subtree search |
Figma API Rate Limits | High risk during agent loops | Minimal (page fetched once, reused indefinitely) |
Vector Icon Handling | Dumps every vector path & coordinate | Collapsed to single |
Multi-Viewport Support | Single URL per request | Native side-by-side |
CLI Pre-caching | No | Yes ( |
What the Formatters Do
The formatting engine (src/formatter.ts) acts as an intelligent compiler that converts raw Figma node schemas into standard web layout models:
1. Figma Primitives to Standard CSS
Colors & Opacity: Converts Figma float RGBA values (
0..1) into clean#HEXorrgba(r, g, b, a).Gradients: Computes rotation angles from Figma handle vectors to generate standard CSS
linear-gradient(deg, ...)andradial-gradient(...).Auto-Layout to Flexbox: Translates Figma auto-layout properties into CSS flex properties:
display: flex,flex-direction: row | column,flex-wrap: wrapjustify-content(center,flex-end,space-between)align-items(center,flex-end,baseline)gap: <value>px
Shorthand Box Models: Aggregates individual edge values into CSS shorthands:
padding: 12px 24pxinstead of separate top/right/bottom/left fields.radius: 12pxorradius: 8px 8px 0px 0pxfor multi-corner radii.border: 1px solid #...or directionalborder-width.
Effects & Typography: Converts shadows to CSS
shadow: 0px 4px 16px rgba(...), blurs tobackdrop-filter: blur(...), and type properties into concise font descriptors:700 48px/56px "Inter"; ls: -0.5px; align: center; case: uppercase.
2. Noise & Icon Reduction
Collapsible Vector Detection (
isCollapsibleVectorSubtree): Inspects subtrees containing vector shapes (VECTOR,BOOLEAN_OPERATION,STAR,LINE, etc.) under icon-sized dimensions (≤240×240px). Instead of outputting internal vector geometry, it generates a single entry with dominant colors:- [10:104] ICON/SVG "ArrowRightIcon" (24×24) { color: #ffffff }Invisible Layers: Filters out all hidden layers (
visible: false), preventing debug frames or hidden alternatives from polluting context.
3. Automated Design Token Collector (TokenCollector)
While traversing the node hierarchy, the formatter collects unique design tokens used across the block:
Background & surface colors
Text colors & border colors
Typography definitions
Spacing scales (
gap,padding)Corner radii and elevation shadows
These are rendered at the top of the block response, allowing LLMs to immediately define CSS variables, Tailwind utility classes, or theme tokens.
4. Specialized Formatting Outputs
formatBlockSection(forget_block): Complete design tokens summary + full CSS-like layout tree for the target block.formatOutlineSection(forget_outline): High-level view of top-level frames and sections with dimensions and ready-to-use links for subsequent block queries.formatCacheSection(forcache_design): Compact confirmation detailing cached nodes, dimensions, and child node URLs without flooding the chat with CSS trees.formatCachedList(forlist_cache): Overview of all locally cached files, viewports, and timestamps.
Core Principles
Cache-First: Every request checks the local disk cache (
FIGMA_CACHE_DIR) first — including recursive lookup inside previously cached pages. The Figma API is only called on a cache miss or whenrefresh: trueis passed.Unified Link Parsing: Supports
/design/<fileKey>,/file/<fileKey>, and branch links/branch/<branchKey>with automaticnode-idnormalization (123-456→123:456).Compact Output: Instead of hundreds of kilobytes of raw JSON, the agent receives an aggregated
Design Tokens Summaryand a concise CSS-likeLayout & Styles Tree. Complex vector icon groups are automatically collapsed into a singleICON/SVGentry.Environment-Only Authentication: The Figma personal access token is read strictly from the
FIGMA_TOKENenvironment variable.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Serves your design system and coding standards to coding agents, so they stop guessing.
Give AI agents your deeepSpace design system: components, tokens, styles and code mappings.
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Related MCP Servers
- AlicenseAqualityDmaintenanceCaches Figma file data locally and provides an MCP server for AI agents to search and retrieve design nodes efficiently, minimizing API calls.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Figma design files with local caching to reduce API requests and rate limits, allowing faster and more reliable retrieval of design data for AI tools.31 npm80MIT
- AlicenseNot gradedqualityBmaintenanceProvides token-efficient, read-only Figma inspection for coding agents via MCP, enabling extraction of design specs, screenshots, and assets from bounded node subtrees with local caching.6 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to read and write a user's Figma file through the Figma Plugin API, offline and privately, without API tokens or rate limits.26 npmMIT