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 Desktop, Cursor IDE, 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
Supports Server-Sent Events (SSE) transport for real-time communication
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

Transport Protocols

The server supports two transport mechanisms:

HTTP POST (/mcp) - Standard JSON-RPC 2.0 over HTTP
Server-Sent Events (SSE) (/mcp/sse) - Real-time bidirectional communication via SSE

The SSE transport is recommended for AI clients like Cursor IDE and Claude Desktop as it provides better real-time communication and connection management.

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
```
Or use the local test server:
```
node src/main-local.js
```
Verify the server is running:
```
curl http://localhost:4321/health
```

Test the MCP endpoint:

curl -X POST http://localhost:4321/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	4321	HTTP server port number (overridden by Apify)
`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"

Integration with AI Assistants

🎯 Cursor IDE

Cursor IDE supports MCP servers via SSE transport. Follow these steps to connect:

Step 1: Deploy and Start the Actor

Deploy the Actor to Apify:
```
apify login
apify push
```
Start a new Actor run in Apify Console:
- Go to https://console.apify.com/actors/uyMWRGrQEwz1bA8Mc
- Click "Start" or "Run"
- Use input: {"figmaAccessToken": "your-figma-token"}
- Select "Start Web Server" method
- Wait for "Server is running in long-running mode..." in logs
Get the Container URL:
- In the Actor run details page, copy the Container URL (e.g., https://xxxxx.runs.apify.net)

Step 2: Configure Cursor IDE

Locate your Cursor MCP configuration file:
- macOS: ~/.cursor/mcp.json
- Windows: %APPDATA%\Cursor\mcp.json
- Linux: ~/.config/Cursor/mcp.json

Add the Figma MCP server configuration:

{
  "mcpServers": {
    "figma-mcp-standby": {
      "url": "https://<CONTAINER-ID>.runs.apify.net/mcp/sse",
      "env": {
        "APIFY_TOKEN": "your-apify-api-token"
      }
    }
  }
}

Important: Replace:

<CONTAINER-ID> with your actual Apify container ID from Step 1
your-apify-api-token with your Apify API token (optional, but recommended for authentication)

Save the configuration file

Step 3: Restart Cursor IDE

⚠️ Critical: You must fully restart Cursor IDE for the changes to take effect:

macOS: Press Cmd+Q to fully quit Cursor (not just close the window)
Windows: Close all Cursor windows and ensure it's not running in the background
Linux: Fully quit Cursor from the application menu
Wait 5-10 seconds, then reopen Cursor IDE
Verify the connection:
- Go to Settings → MCP
- Look for figma-mcp-standby in the list
- It should show a green status indicating it's connected

Step 4: Test the Connection

Once connected, you can test the Figma MCP tools by asking Cursor:

"What Figma MCP tools are available?"
"Analyze Figma file [FILE_KEY]"
"List components in Figma file [FILE_KEY]"
"Export node [NODE_ID] from Figma file [FILE_KEY]"

Automated Configuration Update (Optional)

For convenience, you can use the provided script to automatically update your Cursor config when starting a new Actor run:

cd /path/to/figma_mcp_actor
export APIFY_TOKEN="your-apify-api-token"
./update-mcp-config.sh

This script will:

Find the latest running Actor run
Extract the container URL
Update your ~/.cursor/mcp.json automatically
Create a backup of your existing config

🎯 Claude Desktop

Claude Desktop supports MCP servers via HTTP transport. Follow these steps:

Step 1: Deploy and Start the Actor

Deploy the Actor to Apify (same as Cursor IDE Step 1)
Start a new Actor run and get the Container URL

Step 2: Configure Claude Desktop

Locate your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Add the Figma MCP server configuration:

{
  "mcpServers": {
    "figma-standby": {
      "command": "npx",
      "args": [
     "-y",
     "mcp-remote",
     "https://<CONTAINER-ID>.runs.apify.net/mcp/sse?token=your apify api token"
   ]
    }
  }
}

Note: Claude Desktop uses HTTP transport (/mcp endpoint), not SSE.

Save the configuration file

Step 3: Restart Claude Desktop

⚠️ Critical: You must fully restart Claude Desktop:

macOS: Press Cmd+Q to fully quit Claude Desktop
Windows: Close all Claude Desktop windows
Linux: Fully quit Claude Desktop from the application menu
Wait 5-10 seconds, then reopen Claude Desktop
Verify the connection:
- Check Claude Desktop settings or logs for MCP server status
- The Figma MCP server should appear in the available MCP servers list

Important Limitations & Troubleshooting

⚠️ Ephemeral Container URLs

The Challenge:

Apify assigns a unique container URL for each Actor run
When you start a new run, you get a new container URL
AI clients (Cursor IDE, Claude Desktop) cache the connection URL
If the URL changes, the client continues using the old cached URL, causing connection failures

The Solution:

Every time you start a new Actor run:
- Update your MCP configuration file (mcp.json or claude_desktop_config.json) with the new container URL
- Fully restart the AI client application
Use the automated update script (for Cursor IDE):
```
./update-mcp-config.sh
```
Keep Actor runs running as long as you need the connection (don't stop them unless necessary)

🔄 Connection Issues

Problem: "Connection failed" or "Server not found"

Solutions:

Verify the Actor is still running:
- Check Apify Console → Actor runs
- Ensure status is RUNNING (not READY, SUCCEEDED, or FAILED)
Check the container URL:
- Go to Actor run details in Apify Console
- Verify the Container URL matches what's in your config file
- Test the URL manually: curl https://<container-url>/health
Clear client cache and restart:
- Cursor IDE: Fully quit (Cmd+Q), wait 10 seconds, reopen
- Claude Desktop: Fully quit, wait 10 seconds, reopen
- Sometimes you may need to toggle the MCP server OFF and ON in settings
Verify configuration file syntax:
- Ensure JSON is valid (no trailing commas, proper quotes)
- Check file path is correct for your OS

Problem: "Protocol already initialized" error

Solution:

This is normal during reconnection attempts
The server now supports idempotent initialization
If you see this error repeatedly, fully restart the client

Problem: Tools not appearing in client

Solutions:

Verify connection status:
- Check that the MCP server shows as "connected" (green status)
Check client logs:
- Cursor IDE: View → Output → Select "MCP" from dropdown
- Look for initialization errors or connection issues
Reinitialize the connection:
- Toggle the MCP server OFF and ON in client settings
- Or fully restart the client
Verify Actor is still running:
- Container URLs expire when Actor runs stop
- Start a new run if needed

🚀 Best Practices

Keep Actor runs running while actively using the MCP server
Use the automated update script when starting new runs (Cursor IDE)
Always fully restart the AI client after updating the config
Monitor Actor run status in Apify Console
Plan for migration to a stable URL host (Railway, Render, etc.) for production use

🔮 Future Improvements

For production use, consider migrating to a cloud service with stable URLs:

Railway - Easy deployment with persistent URLs
Render - Free tier available, stable URLs
Fly.io - Global edge deployment
DigitalOcean App Platform - Simple deployment

This would eliminate the need to update configs and restart clients each time.

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

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, including SSE endpoint information.

MCP Protocol Endpoints

HTTP Transport

POST /mcp

Main endpoint for MCP JSON-RPC 2.0 protocol communication over HTTP.

SSE Transport

GET /mcp/sse

Establishes a Server-Sent Events connection for real-time bidirectional communication.

POST /mcp/messages

Sends JSON-RPC messages over an active SSE connection.

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: 4321, but Apify overrides this)
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 HTTP Endpoint: https://<containerId>.runs.apify.net/mcp
MCP SSE Endpoint: https://<containerId>.runs.apify.net/mcp/sse

Important: The container URL is unique per run and expires when the run stops.

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

SSE Connection Issues

Ensure you're using the /mcp/sse endpoint (not /mcp)
Check that the Actor run is still RUNNING
Verify the container URL is correct and accessible
Check Cursor IDE logs for SSE-specific errors

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 (Apify)
│   ├── main-local.js          # Local test server
│   ├── mcp/                    # MCP protocol implementation
│   │   ├── server.js
│   │   ├── protocol.js
│   │   ├── handlers.js
│   │   └── sse-handlers.js     # SSE transport handlers
│   ├── 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
Ephemeral URLs: Apify container URLs expire when runs stop, requiring config updates and client restarts

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
Review Model Context Protocol Specification
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
SSE transport support for real-time communication
Idempotent initialization for client reconnections

Built with ❤️ using Apify Actors and Model Context Protocol

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.actor		.actor
.github/workflows		.github/workflows
source-code		source-code
src		src
.gitignore		.gitignore
.nojekyll		.nojekyll
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
apify_actors_guide.md		apify_actors_guide.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json

License

oabolade/figma_mcp_server_actor

Folders and files

Latest commit

History

Repository files navigation

Figma MCP Server

Overview

Key Features

🎨 Real-time Design File Analysis

🧩 Component Extraction & Management

📦 Automated Asset Export

💬 Collaborative Comment Management

🔧 Design Element Modification

📊 Project & Team Management

Architecture

Transport Protocols

Getting Started

Prerequisites

Installation

Local Development

Configuration

Input Parameters

Environment Variables

Integration with AI Assistants

🎯 Cursor IDE

Step 1: Deploy and Start the Actor

Step 2: Configure Cursor IDE

Step 3: Restart Cursor IDE

Step 4: Test the Connection

Automated Configuration Update (Optional)

🎯 Claude Desktop

Step 1: Deploy and Start the Actor

Step 2: Configure Claude Desktop

Step 3: Restart Claude Desktop

Important Limitations & Troubleshooting

⚠️ Ephemeral Container URLs

🔄 Connection Issues

Problem: "Connection failed" or "Server not found"

Problem: "Protocol already initialized" error

Problem: Tools not appearing in client

🚀 Best Practices

🔮 Future Improvements

MCP Protocol Implementation

Tools

File Analysis Tools

Component Extraction Tools

Asset Export Tools

Comment Management Tools

Design Modification Tools

Resources

Prompts

API Endpoints

Health Check

Root Endpoint

MCP Protocol Endpoints

HTTP Transport

SSE Transport

Deployment to Apify Platform

1. Login to Apify

2. Push the Actor

3. Configure Input

4. Run the Actor

Authentication

Personal Access Token (Current)

OAuth 2.0 (Planned)

Error Handling

Rate Limiting

Troubleshooting

Server Not Starting

Authentication Errors

MCP Protocol Errors

SSE Connection Issues

Development

Project Structure

Running Tests

Code Formatting

Linting

Limitations

Contributing

Packages