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

Clone or download this Actor
Install dependencies:
npm install
Configure your Figma access token:
Create storage/key_value_stores/default/INPUT.json:
{ "figmaAccessToken": "your-figma-personal-access-token", "port": 8080 }

Local Development

Run the Actor locally:
apify run
Verify the server is running:
curl http://localhost:8080/health
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)

Go to Figma Settings
Navigate to Personal access tokens
Click Generate new token
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