Figma MCP - Design File Access

Programmatic access to Figma design files through 18 specialized tools covering file retrieval, image export, component/style extraction, and collaboration. Accessed via Code Mode for token-efficient on-demand access.

Core Principle: Design-to-code bridge - Figma MCP enables AI assistants to read and understand design files.

Two Options Available

Option	Name	Type	Best For
A	Official Figma MCP	HTTP (mcp.figma.com)	Simplicity - no install, OAuth login
B	Framelink (3rd-party)	stdio (local)	Code Mode integration, API key auth

Recommendation: Start with Option A (Official) - zero installation, OAuth login, works immediately. See Install Guide for setup details.

---

1. 🎯 WHEN TO USE

Activation Triggers

Use when:

• Retrieving Figma design file structure or content
• Exporting design elements as images (PNG, SVG, PDF)
• Extracting components for design system documentation
• Getting design tokens (colors, typography, effects)
• Managing team projects and files
• Reading or posting design review comments

Keyword Triggers:

• Files: "figma file", "design file", "get design", "figma document"
• Images: "export image", "export png", "export svg", "render node"
• Components: "figma components", "design system", "component library"
• Styles: "design tokens", "figma styles", "colors", "typography"
• Teams: "team projects", "project files", "figma team"
• Comments: "design comments", "review comments", "figma feedback"

Use Cases

Design File Access

• Get complete Figma file structure
• Retrieve specific nodes by ID
• Access file version history
• Navigate page and frame hierarchy

Asset Export

• Export nodes as PNG, JPG, SVG, or PDF
• Control scale factor (0.01-4x)
• Get URLs for embedded images
• Batch export multiple nodes

Design System Documentation

• List all components in a file
• Extract component metadata
• Get team-wide component libraries
• Document component sets

Design Token Extraction

• Get color styles (fills)
• Get typography styles (text)
• Get effect styles (shadows, blurs)
• Get grid styles

Collaboration

• Read comments on designs
• Post review feedback
• Reply to existing comments
• Delete comments

When NOT to Use

Do not use for:

• Creating or editing Figma designs → Use Figma directly
• Real-time collaboration → Use Figma's native features
• File storage/backup → Use Figma's version history
• Design prototyping → Use Figma's prototyping tools

---

2. 🧭 SMART ROUTING

Activation Detection

TASK CONTEXT
    │
    ├─► Need to get Figma file or nodes
    │   └─► Tools: get_file, get_file_nodes
    │
    ├─► Need to export images
    │   └─► Tools: get_image, get_image_fills
    │
    ├─► Need component information
    │   └─► Tools: get_file_components, get_component, get_team_components
    │
    ├─► Need style/token information
    │   └─► Tools: get_file_styles, get_style, get_team_styles
    │
    ├─► Need team/project navigation
    │   └─► Tools: get_team_projects, get_project_files
    │
    └─► Need to manage comments
        └─► Tools: get_comments, post_comment, delete_comment

Resource Router

def route_figma_resources(task):
    """
    Resource Router for mcp-figma skill
    Load references based on task context
    """

    # ──────────────────────────────────────────────────────────────────
    # QUICK START
    # Purpose: First-time usage, verification, basic commands
    # Key Insight: Fastest path to working state
    # ──────────────────────────────────────────────────────────────────
    if task.is_first_use or task.needs_verification:
        return load("references/quick_start.md")

    # ──────────────────────────────────────────────────────────────────
    # COMPLETE REFERENCE
    # Purpose: All 18 tools with descriptions and interfaces
    # Key Insight: Use for discovery or when unsure which tool
    # ──────────────────────────────────────────────────────────────────
    if task.needs_tool_discovery or task.needs_full_reference:
        return load("references/tool_reference.md")

    # Default: SKILL.md covers basic usage

# ══════════════════════════════════════════════════════════════════════
# STATIC RESOURCES (always available, not conditionally loaded)
# ══════════════════════════════════════════════════════════════════════
# assets/tool_categories.md → Priority categorization of all 18 tools

---

3. 🛠️ HOW IT WORKS

Code Mode Invocation

Figma MCP is accessed via Code Mode's call_tool_chain() for token efficiency.

Naming Convention:

figma.figma_{tool_name}

Process Flow:

STEP 1: Discover Tools
       ├─ Use search_tools() for capability-based discovery
       ├─ Use tool_info() for specific tool details
       └─ Output: Tool name and parameters
       ↓
STEP 2: Execute via Code Mode
       ├─ Use call_tool_chain() with TypeScript code
       ├─ Await figma.figma_{tool_name}({params})
       └─ Output: Tool results
       ↓
STEP 3: Process Results
       └─ Parse and present findings

Tool Invocation Examples

// Discover Figma tools
search_tools({ task_description: "figma design components" });

// Get tool details
tool_info({ tool_name: "figma.figma.get_file" });

// Get a Figma file
call_tool_chain({
  code: `
    const file = await figma.figma_get_file({
      fileKey: "abc123XYZ"
    });
    console.log('File:', file.name);
    return file;
  `
});

// Export as image
call_tool_chain({
  code: `
    const images = await figma.figma_get_image({
      fileKey: "abc123XYZ",
      ids: ["1:234"],
      format: "png",
      scale: 2
    });
    return images;
  `
});

// Get components
call_tool_chain({
  code: `
    const components = await figma.figma_get_file_components({
      fileKey: "abc123XYZ"
    });
    return components;
  `
});

Finding Your File Key

The file key is in your Figma URL:

https://www.figma.com/file/ABC123xyz/My-Design
                           └─────────┘
                           This is fileKey

---

4. 📋 RULES

✅ ALWAYS

1. ALWAYS use Code Mode for Figma invocation

   • Call via call_tool_chain() with TypeScript
   • Saves context tokens vs native MCP

2. ALWAYS use full tool naming convention

   • Format: figma.figma_{tool_name}
   • Example: figma.figma_get_file({ fileKey: "abc" })

3. ALWAYS verify file key format

   • Extract from Figma URL
   • Should be alphanumeric string

4. ALWAYS handle pagination for team queries

   • Use page_size and cursor parameters
   • Check for cursor in response for more pages

5. ALWAYS check API key before operations

   • Use figma_check_api_key() to verify
   • Token must be valid and not expired

❌ NEVER

1. NEVER skip the figma_ prefix in tool names

   • Wrong: await figma.get_file({})
   • Right: await figma.figma_get_file({})

2. NEVER hardcode Figma tokens

   • Use environment variables
   • Store in .env file

3. NEVER assume node IDs are stable

   • Node IDs can change when designs are edited
   • Re-fetch if operations fail

4. NEVER ignore rate limits

   • Figma API has rate limits
   • Add delays for batch operations

⚠️ ESCALATE IF

1. ESCALATE IF authentication fails repeatedly

   • Token may be expired
   • Regenerate in Figma settings

2. ESCALATE IF file not found

   • Verify file key from URL
   • Check file permissions

3. ESCALATE IF rate limited

   • Wait before retrying
   • Reduce request frequency

---

5. 🏆 SUCCESS CRITERIA

File Access Complete

File access complete when:

• ✅ get_file returns file structure
• ✅ File name and pages accessible
• ✅ Node hierarchy navigable

Image Export Complete

Image export complete when:

• ✅ get_image returns image URLs
• ✅ URLs are accessible and valid
• ✅ Format and scale as requested

Component Extraction Complete

Component extraction complete when:

• ✅ get_file_components returns component list
• ✅ Component names and keys accessible
• ✅ Node IDs available for further queries

Style Extraction Complete

Style extraction complete when:

• ✅ get_file_styles returns style list
• ✅ Style types categorized (FILL, TEXT, EFFECT, GRID)
• ✅ Style names and keys accessible

Validation Checkpoints

Checkpoint	Validation
tools_discovered	search_tools() returns Figma tools
auth_verified	check_api_key() confirms token
file_accessible	get_file() returns file data
export_working	get_image() returns URLs

---

6. 🔌 INTEGRATION POINTS

Prerequisites

Before using this skill, ensure:

1. mcp-code-mode skill is available - Figma is accessed through Code Mode
2. Figma configured in .utcp_config.json - NOT in opencode.json
3. Figma Personal Access Token - Stored in .env file

Dependency Chain:
┌─────────────────────────────────────────────────────────────────┐
│  mcp-code-mode skill (REQUIRED)                                 │
│  └─► Provides: call_tool_chain(), search_tools(), etc.          │
│      └─► Enables: Access to Figma provider                      │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  mcp-figma skill (THIS SKILL)                                    │
│  └─► Provides: Knowledge of 18 Figma tools                      │
│      └─► Pattern: figma.figma_{tool_name}                         │
└─────────────────────────────────────────────────────────────────┘

Code Mode Dependency (REQUIRED)

⚠️ CRITICAL: This skill REQUIRES mcp-code-mode. Figma tools are NOT accessible without Code Mode.

How Figma Relates to Code Mode:

┌─────────────────────────────────────────────────────────────────┐
│  opencode.json                                                  │
│  └─► Configures: code-mode MCP server                            │
│      └─► Points to: .utcp_config.json                            │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  .utcp_config.json                                               │
│  └─► Configures: figma provider (among others)                    │
│      └─► Package: figma-developer-mcp                            │
│      └─► Auth: FIGMA_API_KEY                                     │
└─────────────────────────────────────────────────────────────────┘

Figma Provider Configuration (in .utcp_config.json):

{
  "name": "figma",
  "call_template_type": "mcp",
  "config": {
    "mcpServers": {
      "figma": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "figma-developer-mcp", "--stdio"],
        "env": {
          "FIGMA_API_KEY": "figd_your_token_here"
        }
      }
    }
  }
}

Note: Code Mode does NOT support ${VAR} env substitution. You must hardcode the API key directly in the config.

Related Skills

Skill	Relationship	Notes
mcp-code-mode	REQUIRED	Figma accessed via Code Mode's call_tool_chain()
mcp-narsil	Optional	Can analyze code generated from Figma designs

Cross-Tool Workflows

Figma → ClickUp:

// Get design info, create task
const file = await figma.figma_get_file({ fileKey: "abc" });
const task = await clickup.clickup_create_task({
  name: `Implement: ${file.name}`,
  description: `Design file: https://figma.com/file/abc`
});

Figma → Webflow:

// Export images, update CMS
const images = await figma.figma_get_image({ fileKey: "abc", ids: ["1:2"], format: "png" });
// Use image URLs in Webflow CMS

---

7. 🏎️ QUICK REFERENCE

Essential Commands

Task	Tool	Example
Get file	get_file	figma.figma_get_file({ fileKey: "abc123" })
Export image	get_image	figma.figma_get_image({ fileKey: "abc", ids: ["1:2"], format: "png" })
Get components	get_file_components	figma.figma_get_file_components({ fileKey: "abc" })
Get styles	get_file_styles	figma.figma_get_file_styles({ fileKey: "abc" })
Get comments	get_comments	figma.figma_get_comments({ fileKey: "abc" })
Post comment	post_comment	figma.figma_post_comment({ fileKey: "abc", message: "..." })

Common Patterns

// Get file structure
call_tool_chain({
  code: `
    const file = await figma.figma_get_file({ fileKey: "abc123XYZ" });
    console.log('Pages:', file.document.children.map(p => p.name));
    return file;
  `
});

// Export multiple nodes as PNG
call_tool_chain({
  code: `
    const images = await figma.figma_get_image({
      fileKey: "abc123XYZ",
      ids: ["1:234", "1:235", "1:236"],
      format: "png",
      scale: 2
    });
    return images;
  `
});

// Get all components with metadata
call_tool_chain({
  code: `
    const components = await figma.figma_get_file_components({ fileKey: "abc123XYZ" });
    return components.meta.components.map(c => ({
      name: c.name,
      key: c.key,
      nodeId: c.node_id
    }));
  `
});

Troubleshooting

Issue	Solution
"Invalid token" error	Regenerate token in Figma Settings → Personal Access Tokens
File not found	Verify fileKey from URL: figma.com/file/{fileKey}/...
Rate limited	Add delays between requests, reduce batch size
Node ID not found	Node IDs change on edit - re-fetch file to get current IDs
Empty components list	File may not have published components

---

8. 🔗 RELATED RESOURCES

references/

Document	Purpose	Key Insight
tool_reference.md	All 18 tools documented	Complete parameter reference
quick_start.md	Getting started	5-minute setup

assets/

Asset	Purpose
tool_categories.md	Priority categorization of all 18 tools

External Resources

• Figma API Documentation - Official API reference
• Official Figma MCP Server - Figma's official MCP (HTTP at mcp.figma.com) - RECOMMENDED
• figma-developer-mcp - Recommended package for Code Mode integration

Related Skills

• mcp-code-mode - Tool orchestration (Figma accessed via Code Mode)

Install Guide

• MCP - Figma.md - Installation and configuration