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

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:*

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

get-file

Retrieve Figma file details

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

list-files

List files in a Figma project

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

create-variables

Create design system variables

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

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

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
Rate Limiting
- Follows Figma API rate limits
- Implement exponential backoff for better handling
Cache Management
- Default 5-minute TTL
- Limited to 500 entries
- Consider implementing cache invalidation hooks
Authentication
- Only supports personal access tokens
- No support for team-level permissions or collaborative editing
- OAuth implementation planned for future
Technical Implementation
- Requires absolute paths in configuration
- Must compile TypeScript files before execution
- Requires handling both local and global module resolution

Contributing

Fork the repository
Create a feature branch
Make your changes with tests
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

JSON Connection Errors
- Use absolute paths in Claude Desktop configuration
- Ensure the server is built (npm run build)
- Verify all environment variables are set
Authentication Issues
- Verify your Figma access token is valid
- Check the token has required permissions
- Ensure the token is correctly set in configuration
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

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