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

Critical: Rate Limits

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

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

Rate Limit Recovery & Diagnostics

Understanding 429 Responses

When Figma returns HTTP 429, the response includes diagnostic headers:

Common Causes

1. File owned by a Starter/free-plan user

Rate limits are tied to the file owner's plan, not the API token holder's plan. If the user accesses a file owned by someone on a Starter plan, that plan's very low limits apply.

Fix: Duplicate the Figma file into the user's own workspace so their plan's limits apply.

2. Burst pattern from large fetches

Fetching an entire file without depth or nodeId returns megabytes of data, then triggering dozens of image requests for frames with 50-200 children. This burst quickly exhausts rate limits.

Fix: Follow the metadata-first pipeline: depth=2, specific nodeId, images last.

3. View/Collab seat (not Dev/Full seat)

View and Collab seats get only 6 Tier-1 calls per month — not per minute, per month. Any MCP usage will exhaust this almost immediately.

Fix: The user needs a Dev or Full seat on the Figma plan.

4. Plan upgrade propagation delay

After upgrading a Figma plan, new rate limits may take time to propagate. API calls during this window still hit old limits.

Fix: Wait 15-30 minutes after plan upgrade before resuming API usage.

Recovery Strategy

1. Immediate stop — Do not make any more Figma API calls. Each failed retry can extend the lockout window.

2. Diagnose — Ask the user:

• "What Figma plan are you on?" (Starter/Pro/Organization/Enterprise)
• "Do you own this file or is it shared from someone else's workspace?"
• "Have you recently changed your Figma plan?"

3. Wait — Respect the Retry-After duration. Typical lockouts:

• Minor burst: 1-5 minutes
• Sustained burst: 30-60 minutes
• Severe abuse: up to 4-5 days (reported by community)

4. Resume with minimal calls — When retrying:

• Use depth=1 first to verify access is restored
• Follow the metadata-first pipeline strictly
• Space calls at least 5 seconds apart for safety

Alternative Approaches When Rate-Limited

• Work from screenshots: Ask the user to screenshot the Figma design; use vision to generate code
• Work from exported assets: Ask the user to export SVGs/PNGs manually from Figma
• Use Figma's Dev Mode: Suggest the user copy CSS/layout values from Dev Mode manually
• Cache previous responses: If you've already fetched data earlier in the conversation, reuse it — don't re-fetch

Community Solutions

• [Figma-Context-MCP-Cached](https://github.com/pactortester/figma-context-mcp-cached): Community fork that adds local persistent caching with configurable TTL, significantly reducing redundant API calls
• Figma's official MCP server: Figma released their own Dev Mode MCP server with potentially different rate handling — see Figma's help center for setup instructions