Figma Model Context Protocol (MCP) Server

A self-hosted Model Context Protocol (MCP) server that enables Large Language Models (LLMs) and AI agents to interact with Figma designs programmatically. This server acts as a bridge between MCP-compatible clients and the Figma API, allowing AI tools to retrieve design data for generating templates and custom prompts.

Overview

This project implements the Model Context Protocol (MCP) to provide standardized access to Figma resources. It allows AI agents and LLMs to fetch Figma design structures, enabling them to understand and work with design components when generating code, templates, or other creative outputs.

Features

• MCP v1 Protocol Compliance: Implements core MCP methods including listTools and callTool
• Figma API Integration: Secure proxy to Figma's REST API with authentication handling
• Smart Caching: Local caching mechanism to reduce API calls and improve response times
• Rate Limit Handling: Built-in retry logic with exponential backoff for API rate limits
• Node-Specific Access: Supports fetching specific nodes within Figma files
• Depth Control: Configurable depth for retrieving nested design structures

Prerequisites

• Node.js >= 18.0
• Figma Personal Access Token with appropriate permissions

Installation

1. Clone this repository:

   git clone <repository-url>
   cd figma-mcp
   

2. Install dependencies:

   npm install
   

3. Set up your Figma access token as an environment variable:

   export FIGMA_ACCESS_TOKEN="your-personal-access-token-here"
   

Configuration

The server requires a Figma Personal Access Token with appropriate permissions. You can create one in your Figma account settings.

Required permissions typically include:

• Read files (file_read)
• Access to teams/files you want to access

Usage

Start the MCP server:

node index.js

The server will start and listen for MCP requests via stdio. It exposes the following tool:

Available Tool

get_figma_from_url

Retrieves the JSON structure of a Figma file or specific node.

Parameters:

• url (required): The Figma file URL containing the design
• depth (optional): Controls the level of detail (2 or 3 for plans, omit for full structure)

Example:

{
  "name": "get_figma_from_url",
  "arguments": {
    "url": "https://www.figma.com/file/FILE_KEY/...",
    "depth": 2
  }
}

How It Works

1. The server registers an MCP-compatible tool called get_figma_from_url
2. When called, it extracts the file key and node ID (if specified) from the provided URL
3. It makes authenticated requests to the Figma API using the provided access token
4. Results are cached locally for 1 hour to optimize performance
5. Responses are formatted according to MCP specifications

Integration with AI Tools

This server is designed to work with MCP-compatible AI tools such as:

• Cursor
• Claude Desktop
• Other MCP-enabled IDEs and AI assistants

Once running, these tools can discover and communicate with the server to access Figma design data.

Customization for LLM Prompts

The server is particularly useful for:

• Retrieving design specifications to inform code generation
• Extracting component structures for template creation
• Providing design context to LLMs for frontend development
• Converting Figma designs to various code formats

Security Considerations

• Store your Figma access token securely as an environment variable
• The server relies on the MCP host for authentication and authorization
• Run the server in a secure environment with appropriate network isolation
• Tokens should have the minimum required permissions

Caching

The server implements a local caching mechanism:

• Cache directory: .figma_cache in the project root
• Cache TTL: 1 hour (3,600,000 milliseconds)
• Cache keys are generated using MD5 hashes of API endpoints

Rate Limiting

The server includes built-in rate limiting support:

• Automatic retry with exponential backoff for 429 responses
• Maximum of 3 retry attempts
• Starting backoff of 2 seconds, doubling each attempt

Error Handling

Common error responses include:

• Invalid URL format
• Rate limit exceeded (429) with guidance to wait
• General API errors with descriptive messages
• System errors with detailed error messages

Development

To extend the server with additional tools:

1. Register new tools in the ListToolsRequestSchema handler
2. Implement the corresponding logic in the CallToolRequestSchema handler
3. Ensure responses conform to MCP content standards

License

ISC License

Support

If you encounter issues or have questions:

1. Verify your Figma access token is valid and has appropriate permissions
2. Check that your Figma file URLs are accessible
3. Review the server logs for error details