Figma MCP Server

A TypeScript server implementing the Model Context Protocol (MCP) for the Figma API, enabling standardized context provision for LLMs.

Overview

This server provides MCP-compliant access to Figma resources, allowing LLM applications to seamlessly integrate with Figma files, components, and variables. It implements the full MCP specification while providing specialized handlers for Figma's unique resource types.

Key Features

MCP Resource Handlers
- Figma files access and manipulation
- Variables and components management
- Custom URI scheme (figma:///)
Robust Implementation
- Type-safe implementation using TypeScript
- Request validation using Zod schemas
- Comprehensive error handling
- Token validation and API integration
- Batch operations support

Project Structure

figma-mcp-server/
├── src/
│   ├── index.ts         # Main server implementation
│   ├── types.ts         # TypeScript types & interfaces
│   ├── schemas.ts       # Zod validation schemas
│   ├── errors.ts        # Error handling
│   ├── handlers/        # Resource handlers
│   │   ├── file.ts     # File resource handler
│   │   ├── component.ts # Component resource handler
│   │   └── variable.ts  # Variable resource handler
│   └── middleware/      # Server middleware
│       ├── auth.ts      # Authentication middleware
│       └── rate-limit.ts# Rate limiting middleware
├── tests/
│   └── api.test.ts      # API tests
└── package.json

Installation

npm install @modelcontextprotocol/sdk
npm install

Configuration

Set up your Figma access token:
export FIGMA_ACCESS_TOKEN=your_access_token
Configure the server (optional):
export MCP_SERVER_PORT=3000 export RATE_LIMIT_REQUESTS=500 # Requests per 15 minutes export DEBUG=figma-mcp:* # Enable debug logging

Usage

Starting the Server

npm run build
npm run start

Using as an MCP Server

The server implements the Model Context Protocol, making it compatible with any MCP client. It supports both stdio and SSE transports:

stdio Transport

figma-mcp-server < input.jsonl > output.jsonl

SSE Transport

figma-mcp-server --transport sse --port 3000

Client Integration

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Initialize the client
const transport = new StdioClientTransport({
  command: "path/to/figma-mcp-server",
});

const client = new Client({
  name: "figma-client",
  version: "1.0.0",
}, {
  capabilities: {
    resources: {} // Enable resources capability
  }
});

await client.connect(transport);

// Example operations
const resources = await client.request(
  { method: "resources/list" },
  ListResourcesResultSchema
);

Resource URIs

The server implements a custom figma:/// URI scheme for accessing Figma resources:

Files: figma:///file/{file_key}
Components: figma:///component/{file_key}/{component_id}
Variables: figma:///variable/{file_key}/{variable_id}
Styles: figma:///style/{file_key}/{style_id}
Teams: figma:///team/{team_id}
Projects: figma:///project/{project_id}

Error Handling

MCP Protocol Errors

-32700: Parse error
-32600: Invalid request
-32601: Method not found
-32602: Invalid parameters
-32603: Internal error

Resource Errors

100: Resource not found
101: Resource access denied
102: Resource temporarily unavailable

Figma API Errors

The server handles Figma API errors and maps them to appropriate MCP error codes:

403 Forbidden: Maps to error code 101 (Resource access denied)
{ "code": 101, "message": "Access to Figma resource denied", "data": { "figmaError": "Invalid access token" } }
404 Not Found: Maps to error code 100 (Resource not found)
{ "code": 100, "message": "Figma resource not found", "data": { "uri": "figma:///file/invalid_key" } }
429 Too Many Requests: Maps to error code 102 (Resource temporarily unavailable)
{ "code": 102, "message": "Figma API rate limit exceeded", "data": { "retryAfter": 300 } }

Rate Limiting

The server implements smart rate limiting to prevent hitting Figma API limits:

Default limit: 500 requests per 15 minutes
Automatic retry handling for rate-limited requests
Configurable rate limit via environment variables
Rate limit status endpoint: GET /rate-limit-status

Rate limit headers are included in responses:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 486
X-RateLimit-Reset: 1623456789

Development

Setting Up Development Environment

npm install
npm run build

Running Tests

npm test

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Current Status and Roadmap

Implemented Features

Basic MCP server implementation
File resource handling
Component resource handling
Variable resource handling
Authentication middleware
Rate limiting
Error mapping
Basic test coverage

Upcoming Features

WebSocket transport support (In Progress)
Resource change notifications
Caching layer implementation
Plugin system for custom handlers
Enhanced test coverage
Performance optimizations
Batch operation improvements
Documentation expansion

Debugging

Enable debug logging by setting the DEBUG environment variable:

DEBUG=figma-mcp:* npm start

Debug namespaces:

figma-mcp:server: Server operations
figma-mcp:handler: Resource handlers
figma-mcp:api: Figma API calls
figma-mcp:rate-limit: Rate limiting

License

This project is licensed under the MIT License - see the LICENSE file for details.