figma-context-mcp

Figma Context MCP

Expert guide for the Figma Context MCP (also known as Framelink). Teaches efficient API usage patterns that prevent 429 rate-limit lockouts.

Tools

Tool	Purpose	API Tier
get_figma_data	Fetch file/node structure, layout, components	Tier 1 (most restricted)
download_figma_images	Export PNG/SVG renders of specific nodes	Tier 2-3

Critical: Rate Limits

Figma enforces per-plan rate limits. Limits apply based on the file owner's plan, not yours:

Tier	Starter	Pro	Org
Tier 1 (files)	10/min	15/min	20/min
Tier 2 (images)	25/min	50/min	100/min
Tier 3	50/min	100/min	150/min

View/Collab seats get only 6 Tier-1 calls/month. If accessing files owned by someone on a Starter/free plan, their limits apply to you.

429 lockouts can last 4-5 days. Prevention is essential.

Workflow: Metadata-First Pipeline

Never fetch everything upfront. Adopt this pipeline to keep most jobs under 2-3 API calls and <500 KB:

1. Start with a targeted node, not the whole file

When a user provides a Figma URL like figma.com/design/FILEKEY/Name?node-id=123-456, always extract and pass the nodeId. Never fetch the entire file when a specific node is available.

get_figma_data(fileKey="ABC123", nodeId="123-456", depth=2)

2. Use minimal depth

Always set depth to limit tree traversal:

• depth=1: Top-level frame only (layout structure, component names)
• depth=2: Frame + direct children (usually sufficient for code generation)
• depth=3: Maximum recommended — only when nested auto-layouts require it

Default if omitted: the API returns the ENTIRE subtree — often megabytes for complex frames with 50-200+ children. This is the #1 cause of 429 errors.

3. Analyze locally before fetching more

After receiving the initial response:

• Identify which child nodes actually need detail (skip hidden, decorative, or library-referenced nodes)
• Extract design tokens (colors, spacing, typography) directly from the response — no extra calls needed
• Build your component structure from what you already have

4. Fetch deeper nodes only if necessary

If a specific child node needs more detail, fetch just that node:

get_figma_data(fileKey="ABC123", nodeId="child-node-id", depth=1)

5. Download images last, in small batches

Only request images for the final deduplicated set of visual assets you actually need:

• Deduplicate by imageRef — multiple nodes can reference the same fill image
• Batch into groups of 5-10 nodes per call
• Use pngScale=1 unless the user specifically needs @2x/@3x assets

download_figma_images(
  fileKey="ABC123",
  nodes=[{nodeId: "1:2", fileName: "hero", ...}],  # max 5-10 per call
  localPath="./assets",
  pngScale=1
)

When You Hit a 429

See references/rate-limit-recovery.md for diagnostics and recovery steps.

Quick checklist:

1. Stop all Figma API calls immediately — additional calls extend the lockout
2. Check if the file is owned by a Starter/free-plan user (limits are per-owner)
3. If the user has a Pro/Org plan, suggest duplicating the file into their own workspace
4. Wait for Retry-After header duration before retrying
5. When retrying, use the minimal-depth pipeline above

Common Patterns

Design-to-code (single component)

1. get_figma_data with specific nodeId + depth=2 (1 call)
2. Generate code from response — no image calls unless the component contains raster assets
3. If images needed: download_figma_images for just the raster fills (1 call)
4. Total: 1-2 API calls

Design-to-code (full page)

1. get_figma_data with page nodeId + depth=1 to get frame list (1 call)
2. Identify the 2-3 key frames that matter
3. get_figma_data for each key frame with depth=2 (2-3 calls)
4. Extract tokens locally, download only unique raster assets (1 call)
5. Total: 4-5 API calls

Extract design tokens only

1. get_figma_data with nodeId + depth=2 (1 call)
2. Parse colors, typography, spacing from the response — no image calls needed
3. Total: 1 API call

Anti-Patterns

Pattern	Problem	Fix
Omitting depth	Returns entire subtree (MB of data)	Always set depth=2 or less
Omitting nodeId	Fetches entire file	Always extract nodeId from URL
Downloading all images upfront	Bursts of image requests hit Tier 2 limits	Download only final deduplicated set
Retrying on 429	Extends lockout duration	Stop, wait for Retry-After, then resume with minimal calls
Fetching library components	Remote library nodes trigger extra API calls	Use local component data from initial response