Figma MCP Server

A Model Context Protocol (MCP) server Actor for Apify that enables AI assistants and applications to interact with Figma designs and projects using natural language commands. This Actor creates a secure bridge between AI models and the Figma API, allowing users to query design information, extract asset details, modify design elements, and retrieve project metadata without manually navigating the Figma interface.

Overview

The Figma MCP Server Actor establishes a long-running HTTP server that implements the Model Context Protocol, enabling seamless integration between AI assistants (like Claude, ChatGPT, and custom AI workflows) and Figma's design platform. It provides a comprehensive set of tools, resources, and prompts for interacting with Figma files, components, assets, and projects.

Key Features

🎨 Real-time Design File Analysis

• Analyze Figma file structure and extract metadata
• Extract design tokens, styles, and component information
• Get hierarchical file structures with customizable depth

🧩 Component Extraction & Management

• List all components and component sets in a file
• Get detailed component information including properties and variants
• Find component usage patterns across files

📦 Automated Asset Export

• Export design assets in multiple formats (PNG, SVG, PDF, JPG)
• Batch export multiple nodes or entire pages
• Configurable scale factors for different display densities

💬 Collaborative Comment Management

• Retrieve comments from Figma files
• Create new comments at specific positions or nodes
• Manage feedback and annotations programmatically

🔧 Design Element Modification

• Get node information for modification planning
• Support for design updates (via Plugin API integration)

📊 Project & Team Management

• Access project metadata and file listings
• Retrieve team projects and organizational information

Architecture

This Actor runs as a long-running HTTP server that:

• Implements the Model Context Protocol (MCP) JSON-RPC 2.0 specification
• Provides RESTful endpoints for health checks and MCP protocol communication
• Maintains persistent connections for interactive AI assistant workflows
• Supports both Personal Access Token (PAT) and OAuth 2.0 authentication

Getting Started

Prerequisites

• Node.js >= 20.0.0
• Apify account (Sign up here)
• Figma account with API access
• Figma Personal Access Token (Generate here)

Installation

1. Clone or download this Actor

2. Install dependencies:

   npm install
   

3. Configure your Figma access token:

   Create storage/key_value_stores/default/INPUT.json:

   {
     "figmaAccessToken": "your-figma-personal-access-token",
     "port": 8080
   }
   

Local Development

1. Run the Actor locally:

   apify run
   

2. Verify the server is running:

   curl http://localhost:8080/health
   

3. Test the MCP endpoint:

   curl -X POST http://localhost:8080/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {}
     }'
   

Configuration

Input Parameters

Parameter	Type	Default	Description
figmaAccessToken	string	-	Personal Access Token for Figma API authentication
port	integer	8080	HTTP server port number
oauthClientId	string	-	OAuth 2.0 client ID (optional, for future use)
oauthClientSecret	string	-	OAuth 2.0 client secret (optional, for future use)
maxConcurrentRequests	integer	10	Maximum concurrent requests (1-100)
enableCaching	boolean	true	Enable response caching for Figma API requests

Environment Variables

You can also set the Figma access token via environment variable:

export FIGMA_ACCESS_TOKEN="your-token-here"

MCP Protocol Implementation

This Actor implements the full Model Context Protocol specification, including:

Tools

The server provides 15+ MCP tools organized into categories:

File Analysis Tools

• analyze_file - Analyze a Figma file structure and extract metadata
• get_file_structure - Get hierarchical file structure with customizable depth
• extract_styles - Extract design tokens, styles, and design system information

Component Extraction Tools

• list_components - List all components available in a Figma file
• get_component_details - Get detailed information about a specific component
• find_component_usage - Find all instances where a component is used

Asset Export Tools

• export_node - Export a specific node as PNG, SVG, PDF, or JPG
• export_multiple_nodes - Export multiple nodes in batch
• export_file_pages - Export all pages from a Figma file

Comment Management Tools

• get_comments - Retrieve all comments from a Figma file
• create_comment - Create a new comment at a position or node
• resolve_comment - Mark a comment as resolved
• delete_comment - Delete a comment

Design Modification Tools

• update_node_properties - Update properties of a design node
• get_node_for_modification - Get detailed node information for modification planning

Resources

The server exposes read-only resources for accessing Figma data:

• figma://file/{fileKey} - File metadata and structure
• figma://components/{fileKey} - Component library
• figma://styles/{fileKey} - Design tokens and styles
• figma://project/{projectId} - Project information
• figma://team/{teamId}/projects - Team projects list

Prompts

Pre-configured prompts for common workflows:

• analyze_design_file - Guide for analyzing Figma design files
• extract_components - Guide for extracting and documenting components
• export_assets - Best practices for asset export
• check_design_system - Design system consistency checks
• manage_feedback - Comment and feedback management guidance

Usage Examples

Example 1: Initialize MCP Connection

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "example-client",
        "version": "1.0.0"
      }
    }
  }'

Example 2: List Available Tools

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Example 3: Analyze a Figma File

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "analyze_file",
      "arguments": {
        "fileKey": "your-figma-file-key"
      }
    }
  }'

Example 4: Export a Component as PNG

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "export_node",
      "arguments": {
        "fileKey": "your-figma-file-key",
        "nodeId": "node-id-to-export",
        "format": "PNG",
        "scale": 2
      }
    }
  }'

Example 5: Read a Resource

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "resources/read",
    "params": {
      "uri": "figma://file/your-figma-file-key"
    }
  }'

API Endpoints

Health Check

GET /health

Returns server status and health information.

Response:

{
  "status": "ok",
  "service": "figma-mcp-server",
  "version": "0.0.1",
  "authenticated": true,
  "timestamp": "2024-11-15T12:00:00.000Z"
}

Root Endpoint

GET /

Returns service information and available endpoints.

MCP Protocol Endpoint

POST /mcp

Main endpoint for MCP JSON-RPC 2.0 protocol communication.

Deployment to Apify Platform

1. Login to Apify

apify login

2. Push the Actor

apify push

3. Configure Input

After deployment, configure the Actor input in the Apify Console:

• Set your figmaAccessToken
• Adjust port if needed (default: 8080)
• Configure other optional parameters

4. Run the Actor

The Actor will start as a long-running server accessible via:

• Container URL: https://<containerId>.runs.apify.net/
• Health Check: https://<containerId>.runs.apify.net/health
• MCP Endpoint: https://<containerId>.runs.apify.net/mcp

Integration with AI Assistants

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "figma": {
      "url": "https://<containerId>.runs.apify.net/mcp",
      "transport": "http"
    }
  }
}

Custom Integration

The server implements the standard MCP protocol, making it compatible with any MCP client:

// Example MCP client usage
const response = await fetch("https://your-actor-url/mcp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "analyze_file",
      arguments: { fileKey: "your-file-key" },
    },
  }),
});

Authentication

Personal Access Token (Current)

1. Go to Figma Settings
2. Navigate to Personal access tokens
3. Click Generate new token
4. Copy the token and use it in the Actor input

OAuth 2.0 (Planned)

OAuth 2.0 support is planned for multi-user scenarios. The structure is in place, and implementation will be added in a future update.

Error Handling

The server implements comprehensive error handling:

• Invalid requests: Returns JSON-RPC 2.0 error responses
• Authentication errors: Clear error messages for missing or invalid tokens
• Figma API errors: Propagates API errors with context
• Network errors: Graceful handling of connection issues

Rate Limiting

The Figma API has rate limits. The Actor includes:

• Response caching (configurable, enabled by default)
• Request queuing for concurrent requests
• Configurable maxConcurrentRequests parameter

Troubleshooting

Server Not Starting

• Verify Node.js version >= 20.0.0
• Check that the port is not already in use
• Ensure figmaAccessToken is provided in input

Authentication Errors

• Verify your Figma Personal Access Token is valid
• Check token permissions in Figma settings
• Ensure token hasn't expired

MCP Protocol Errors

• Verify JSON-RPC 2.0 format is correct
• Check that required parameters are provided
• Review error messages in response

Development

Project Structure

figma_mcp_actor/
├── .actor/
│   ├── actor.json              # Actor configuration
│   ├── input_schema.json       # Input schema
│   ├── output_schema.json      # Output schema
│   └── dataset_schema.json    # Dataset schema
├── src/
│   ├── main.js                # Entry point
│   ├── mcp/                    # MCP protocol implementation
│   │   ├── server.js
│   │   ├── protocol.js
│   │   └── handlers.js
│   ├── figma/                  # Figma API integration
│   │   ├── client.js
│   │   └── auth.js
│   ├── tools/                  # MCP tools
│   ├── resources/              # MCP resources
│   └── prompts/                # MCP prompts
├── Dockerfile
├── package.json
└── README.md

Running Tests

npm test

Code Formatting

npm run format

Linting

npm run lint
npm run lint:fix

Limitations

• Design Modification: Full design modification requires Figma Plugin API (REST API has limited write capabilities)
• Comment Resolution: Some comment operations may require Plugin API integration
• OAuth 2.0: Currently supports Personal Access Tokens; OAuth 2.0 support is planned

Contributing

Contributions are welcome! Please ensure:

• Code follows the existing style
• Tests are added for new features
• Documentation is updated

License

ISC

Support

For issues, questions, or contributions:

• Check the Apify Documentation
• Review Figma API Documentation
• Open an issue in the repository

Changelog

Version 0.0.1

• Initial release
• Full MCP protocol implementation
• Figma API integration with PAT authentication
• 15+ tools for file analysis, component extraction, asset export, and comments
• Resource and prompt support
• Long-running HTTP server architecture

---

Built with ❤️ using Apify Actors and Model Context Protocol