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

Configuration

1. Create a .env file based on .env.example:

2. 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

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

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:

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

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