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.

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%Claudeclaude_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

2. Retrieve Figma file details

   {
     "name": "get-file",
     "arguments": {
       "fileKey": "your_file_key"
     }
   }

3. list-files

4. List files in a Figma project

   {
     "name": "list-files",
     "arguments": {
       "projectId": "your_project_id"
     }
   }

5. create-variables

6. Create design system variables

   {
     "name": "create-variables",
     "arguments": {
       "fileKey": "your_file_key",
       "variables": [
         {
           "name": "primary-color",
           "type": "COLOR",
           "value": "#0066FF"
         }
       ]
     }
   }

7. create-theme

8. 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
2. Limited to read-only operations due to Figma API restrictions
3. Personal access tokens only support read operations, not write
4. Cannot modify variables, components, or styles through REST API with personal tokens

5. Write operations would require Figma plugin development instead

6. Rate Limiting

7. Follows Figma API rate limits

8. Implement exponential backoff for better handling

9. Cache Management

10. Default 5-minute TTL
11. Limited to 500 entries

12. Consider implementing cache invalidation hooks

13. Authentication

14. Only supports personal access tokens
15. No support for team-level permissions or collaborative editing

16. OAuth implementation planned for future

17. Technical Implementation

18. Requires absolute paths in configuration
19. Must compile TypeScript files before execution
20. 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
2. Use absolute paths in Claude Desktop configuration
3. Ensure the server is built (npm run build)

4. Verify all environment variables are set

5. Authentication Issues

6. Verify your Figma access token is valid
7. Check the token has required permissions

8. Ensure the token is correctly set in configuration

9. Server Not Starting

10. Check Node.js version (18.x+ required)
11. Verify the build exists (dist/index.js)
12. Check Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/mcp*.log
    • Windows: %APPDATA%Claudelogsmcp*.log

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

Support

• GitHub Issues: Report a bug
• Documentation: Wiki
• Discord: Join our community