MCP HubMCP Hub
TimHolden

figma-mcp-server

by: TimHolden

Model Context Protocol server implementation for Figma API

115created 28/12/2024
Visit
Figma
Protocol

📌Overview

Purpose: To provide seamless integration with Figma's API through a Model Context Protocol (MCP) server, enabling advanced design token and theme management capabilities.

Overview: The Figma MCP Server is a TypeScript-based server designed for read-only access to Figma files and projects. By leveraging Claude and other MCP-compatible clients, it streamlines the management of design systems while offering a foundation for future feature enhancement as Figma's API evolves.

Key Features:

  • Secure API Authentication: Provides secure access to Figma's API using a personal access token.

  • File Operations: Supports read operations to retrieve file details and list projects within Figma, ensuring efficient file management.

  • Design System Management: Enables the creation and management of design tokens and themes, including variable creation and reference handling.

  • Performance Optimization: Features an LRU caching mechanism, rate limit handling, and connection pooling to enhance server responsiveness.

  • Comprehensive Monitoring: Implements health checks, usage statistics, and error tracking for effective service management.

Figma MCP Server

A Model Context Protocol (MCP) server providing integration with Figma's API through Claude and other MCP-compatible clients. Currently supports read-only access to Figma files and projects, with architecture designed to support advanced design token and theme management features pending Figma API enhancements.

Project Status

Current Progress

  • ✅ Core implementation of a TypeScript MCP server
  • ✅ Tested and functional with Claude Desktop
  • ✅ Read operations: get-file and list-files tools for Figma file access
  • ✅ Implemented caching, error handling, and monitoring
  • ✅ Supports stdio and SSE transport protocols

Potential Full Functionality

Planned features when API restrictions are lifted or via plugin development:

  • Variable management: Create, read, update, delete design tokens
  • Reference handling: Create and validate token relationships
  • Theme management: Multiple modes (e.g., light/dark)
  • Dependency analysis: Circular reference detection
  • Batch operations on variables and themes

Features

  • Secure authentication with Figma API
  • File operations: read and list files
  • Design system management:
    • Variable creation and management
    • Theme creation and configuration
    • Reference handling and validation
  • Performance optimizations:
    • LRU caching
    • Rate limit handling
    • Connection pooling
  • Monitoring:
    • Health checks
    • Usage statistics
    • Error tracking

Prerequisites

  • Node.js 18.x or higher
  • Figma access token with appropriate permissions
  • Basic understanding of MCP (Model Context Protocol)

Installation

npm install figma-mcp-server

Configuration

  1. Create a .env file based on .env.example:
# Figma API Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
DEBUG=figma-mcp:*
  1. Claude Desktop Integration

Configure the server in your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Example configuration:

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-mcp-server/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Notes:

  • Use absolute paths; relative paths will not work
  • On Windows, use double backslashes (\\) in paths
  • Restart Claude Desktop after configuration changes

Usage

Basic Usage

import { startServer } from 'figma-mcp-server';

const server = await startServer(process.env.FIGMA_ACCESS_TOKEN);

Available Tools

  1. get-file - Retrieve Figma file details
{
  "name": "get-file",
  "arguments": {
    "fileKey": "your_file_key"
  }
}
  1. list-files - List files in a Figma project
{
  "name": "list-files",
  "arguments": {
    "projectId": "your_project_id"
  }
}
  1. create-variables - Create design system variables
{
  "name": "create-variables",
  "arguments": {
    "fileKey": "your_file_key",
    "variables": [
      {
        "name": "primary-color",
        "type": "COLOR",
        "value": "#0066FF"
      }
    ]
  }
}
  1. create-theme - Create and configure themes
{
  "name": "create-theme",
  "arguments": {
    "fileKey": "your_file_key",
    "name": "Dark Theme",
    "modes": [
      {
        "name": "dark",
        "variables": [
          {
            "variableId": "123",
            "value": "#000000"
          }
        ]
      }
    ]
  }
}

API Documentation

Server Methods

  • startServer(figmaToken: string, debug?: boolean, port?: number)

    • Initializes and starts the MCP server
    • Returns: Promise

Tool Schemas

Tool inputs are validated using Zod schemas. Example:

const CreateVariablesSchema = z.object({
  fileKey: z.string(),
  variables: z.array(z.object({
    name: z.string(),
    type: z.enum(['COLOR', 'FLOAT', 'STRING']),
    value: z.string(),
    scope: z.enum(['LOCAL', 'ALL_FRAMES'])
  }))
});

Error Handling

  • Invalid token: 403 with error message
  • Rate limiting: 429 with reset time
  • Validation errors: 400 with field-specific details
  • Server errors: 500 with error tracking

Limitations & Known Issues

API Restrictions

  • Read-only operations only due to Figma API limitations
  • Personal access tokens support read but not write operations
  • Write operations require Figma plugin development
  • Rate limiting according to Figma API with exponential backoff
  • Cache management: 5-minute TTL, max 500 entries; cache invalidation hooks suggested
  • Authentication supports only personal access tokens; OAuth support planned
  • Configuration requires absolute paths and compiled TypeScript files

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Implement changes with tests
  4. Submit a pull request

Coding standards:

  • TypeScript strict mode
  • ESLint configuration
  • Jest for testing
  • Comprehensive error handling

License

MIT License

Troubleshooting

Common Issues

  1. JSON Connection Errors
  • Use absolute paths in Claude Desktop configuration
  • Ensure the server is built (npm run build)
  • Verify environment variables are set
  1. Authentication Issues
  • Verify Figma access token validity and permissions
  • Ensure the token is correctly set in configuration
  1. Server Not Starting
  • Check Node.js version (18.x or higher)
  • Verify dist/index.js exists
  • Check Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/mcp*.log
    • Windows: %APPDATA%\Claude\logs\mcp*.log

Refer to the troubleshooting guide for more detailed steps.

Support

  • GitHub Issues: Report bugs on the repository issue tracker
  • Documentation: Available through the project wiki
  • Discord: Join the community discussion