Skip to main content
Glama

Figma MCP Server

A Model Context Protocol (MCP) server that provides integration with Figma's API through Claude and other MCP-compatible clients. Currently supports read-only access to Figma files and projects, with server-side architecture capable of supporting more advanced design token and theme management features (pending Figma API enhancements or plugin development).

Project Status

Current Progress

  • ✅ Core Implementation: Successfully built a TypeScript server following the Model Context Protocol (MCP)

  • ✅ Claude Desktop Integration: Tested and functional with Claude Desktop

  • ✅ Read Operations: Working get-file and list-files tools for Figma file access

  • ✅ Server Architecture: Caching system, error handling, and stats monitoring implemented

  • ✅ Transport Protocols: Both stdio and SSE transport mechanisms supported

Potential Full Functionality

The server has been designed with code to support these features (currently limited by API restrictions):

  • Variable Management: Create, read, update, and delete design tokens (variables)

  • Reference Handling: Create and validate relationships between tokens

  • Theme Management: Create themes with multiple modes (e.g., light/dark)

  • Dependency Analysis: Detect and prevent circular references

  • Batch Operations: Perform bulk actions on variables and themes

With Figma plugin development or expanded API access, these features could be fully enabled.

Related MCP server: Figma MCP Server

Features

  • 🔑 Secure authentication with Figma API

  • 📁 File operations (read, list)

  • 🎨 Design system management

    • Variable creation and management

    • Theme creation and configuration

    • Reference handling and validation

  • 🚀 Performance optimized

    • LRU caching

    • Rate limit handling

    • Connection pooling

  • 📊 Comprehensive 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. For Claude Desktop integration:

The server can be configured in your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Important Notes:

  • Use ABSOLUTE paths, not relative paths

  • On Windows, use double backslashes (\\) in paths

  • Restart Claude Desktop after making 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"
      }
    }
  2. list-files

    • List files in a Figma project

    {
      "name": "list-files",
      "arguments": {
        "projectId": "your_project_id"
      }
    }
  3. create-variables

    • Create design system variables

    {
      "name": "create-variables",
      "arguments": {
        "fileKey": "your_file_key",
        "variables": [
          {
            "name": "primary-color",
            "type": "COLOR",
            "value": "#0066FF"
          }
        ]
      }
    }
  4. 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

All tool inputs are validated using Zod schemas:

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

The server provides detailed error messages and proper error codes:

  • Invalid token: 403 with specific 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

  1. Read-Only Operations

    • Limited to read-only operations due to Figma API restrictions

    • Personal access tokens only support read operations, not write

    • Cannot modify variables, components, or styles through REST API with personal tokens

    • Write operations would require Figma plugin development instead

  2. Rate Limiting

    • Follows Figma API rate limits

    • Implement exponential backoff for better handling

  3. Cache Management

    • Default 5-minute TTL

    • Limited to 500 entries

    • Consider implementing cache invalidation hooks

  4. Authentication

    • Only supports personal access tokens

    • No support for team-level permissions or collaborative editing

    • OAuth implementation planned for future

  5. Technical Implementation

    • Requires absolute paths in configuration

    • Must compile TypeScript files before execution

    • Requires handling both local and global module resolution

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes with tests

  4. Submit a pull request

Please follow our coding standards:

  • TypeScript strict mode

  • ESLint configuration

  • Jest for testing

  • Comprehensive error handling

License

MIT License - See LICENSE file for details

Troubleshooting

See TROUBLESHOOTING.md for a comprehensive troubleshooting guide.

Common Issues

  1. JSON Connection Errors

    • Use absolute paths in Claude Desktop configuration

    • Ensure the server is built (npm run build)

    • Verify all environment variables are set

  2. Authentication Issues

    • Verify your Figma access token is valid

    • Check the token has required permissions

    • Ensure the token is correctly set in configuration

  3. Server Not Starting

    • Check Node.js version (18.x+ required)

    • Verify the build exists (dist/index.js)

    • Check Claude Desktop logs:

      • macOS: ~/Library/Logs/Claude/mcp*.log

      • Windows: %APPDATA%\Claude\logs\mcp*.log

For more detailed debugging steps and solutions, refer to the troubleshooting guide.

Support

Available Tools

2 tools
get-fileA

Get details of a Figma file

Inputs: fileKey (required).

list-filesB

List files in a Figma project

Inputs: projectId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools are clearly distinct: one retrieves details of a specific file, the other lists files in a project. There is no overlap or ambiguity.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun pattern (get-file, list-files) using snake_case, making them predictable and readable.

    Tool Count3/5

    With only 2 tools, the server feels very thin for a full Figma integration. While the count is borderline, it is still usable for basic file listing and retrieval.

    Completeness2/5

    The server lacks critical operations such as creating, updating, or deleting files, and does not cover other common Figma resources like components or styles. This is a significant gap for expected Figma workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers