@gongrzhe/figma-developer-mcp

Figma MCP Server

A Model Context Protocol (MCP) server for Figma integration, enabling AI assistants to fetch design data and download assets from Figma files.

Features

• Design Data Access: Fetch complete file structure and node information from Figma files
• Asset Download: Download SVG and PNG images directly from Figma designs
• Node Traversal: Navigate specific nodes or entire file structures with configurable depth
• Multiple Formats: Support for both YAML and JSON output formats
• API Token Authentication: Secure access via Figma Personal Access Tokens
• HTTP Transport: RESTful API interface for web applications

Quick Start

Starting the Server

# Start HTTP server on port 3000 (default)
npm start

# Build and start
npm run build && npm start

The server runs in HTTP mode only and provides:

• POST /mcp - Main MCP endpoint for tool execution
• GET /health - Health check endpoint

Authentication

All requests require a Figma Personal Access Token via headers:

FIGMA_API_KEY: fig_your_figma_token_here

Create a Figma Personal Access Token in your Figma account settings.

Tools

The server provides 2 tools for comprehensive Figma API access. Each tool requires FIGMA_API_KEY header.

1. get_figma_data

Fetch layout information and design data from Figma files.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "FIGMA_API_KEY: fig_your_figma_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "get_figma_data",
      "arguments": {
        "fileKey": "abc123def456",
        "nodeId": "1:23",
        "depth": 2
      }
    }
  }'

Parameters:

• fileKey (required): The Figma file key from the URL (e.g., figma.com/file/<fileKey>/)
• nodeId (optional): Specific node ID to fetch (use when available from URL node-id=<nodeId>)
• depth (optional): Traversal depth limit (only use when explicitly requested)

2. download_figma_images

Download SVG and PNG images from Figma design nodes.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "FIGMA_API_KEY: fig_your_figma_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2", 
    "method": "tools/call",
    "params": {
      "name": "download_figma_images",
      "arguments": {
        "fileKey": "abc123def456",
        "nodes": [
          {
            "nodeId": "1:23",
            "fileName": "icon.svg"
          },
          {
            "nodeId": "1:24", 
            "imageRef": "imageRef123",
            "fileName": "background.png"
          }
        ],
        "localPath": "/path/to/save/images",
        "pngScale": 2,
        "svgOptions": {
          "outlineText": true,
          "includeId": false,
          "simplifyStroke": true
        }
      }
    }
  }'

Parameters:

• fileKey (required): The Figma file key containing the nodes
• nodes (required): Array of nodes to download as images
  • nodeId: Node ID formatted as "1234:5678"
  • imageRef (optional): Required for image fill nodes, leave blank for vector SVGs
  • fileName: Local filename for the saved file
• localPath (required): Absolute directory path where images will be saved
• pngScale (optional): Export scale for PNG images (default: 2)
• svgOptions (optional): SVG export configuration
  • outlineText: Whether to outline text (default: true)
  • includeId: Whether to include IDs (default: false)
  • simplifyStroke: Whether to simplify strokes (default: true)

List Available Tools

Get the complete list of available tools:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "FIGMA_API_KEY: fig_your_figma_token_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-list",
    "method": "tools/list",
    "params": {}
  }'

Configuration

Environment Variables

Create a .env file in your project root:

# Figma API Configuration
FIGMA_API_KEY=fig_your_figma_token_here

# Server Configuration  
PORT=3000
OUTPUT_FORMAT=yaml

Output Formats

The server supports two output formats:

• YAML (default): Human-readable format ideal for viewing design structure
• JSON: Machine-readable format for programmatic processing

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/path/to/figma-mcp/dist/cli.js"],
      "env": {
        "FIGMA_API_KEY": "fig_your_figma_token_here",
        "PORT": "3000"
      }
    }
  }
}

Installation

NPM

npm install @gongrzhe/figma-developer-mcp

From Source

git clone https://github.com/gongrzhe/figma-developer-mcp.git
cd figma-developer-mcp
npm install
npm run build

Authentication Setup

• Get Figma Personal Access Token:

  • Go to Figma Account Settings
  • Navigate to "Personal access tokens"
  • Create a new token with appropriate permissions
  • Copy the generated token (starts with fig_)

• Configure Token:

  • Add to .env file: FIGMA_API_KEY=fig_your_token_here
  • Or pass via FIGMA_API_KEY header in each request

Use Cases

Design Implementation

• Extract component structures and properties
• Get design tokens (colors, typography, spacing)
• Understand layout hierarchies and constraints
• Implement responsive designs based on Figma frames

Asset Management

• Download icons and illustrations in multiple formats
• Export images at different scales for various devices
• Batch download design assets for development
• Maintain consistent asset naming and organization

Design System Integration

• Sync design tokens with code
• Validate implementation against designs
• Automate asset pipeline workflows
• Generate style guides from Figma files

Error Handling

The server provides detailed error messages for common issues:

• 401: Invalid Figma API token
• 403: Insufficient permissions for file access
• 404: File or node not found
• 429: Rate limit exceeded
• 500: Internal server errors

Figma File Structure

When working with Figma files, understand these key concepts:

File Keys

Found in Figma URLs: figma.com/file/<fileKey>/design-name

Node IDs

Found in Figma URLs as parameters: node-id=<nodeId> Format: "number:number" (e.g., "1:23")

Image References

Special identifiers for image fills within nodes Required when downloading bitmap images vs. vector graphics

Development

Build

npm run build

Test

npm test

Development Mode

npm run dev

License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.