🎨 Figma MCP Server

A production-ready Model Context Protocol (MCP) server that seamlessly integrates Figma with AI assistants like Claude. Features OAuth with automatic token refresh, eliminating the need for manual token updates every 30 days.

✨ Key Features

• 🔐 OAuth with Auto-Refresh: Never manually update Figma tokens again - automatic refresh every 30 days
• 🤖 MCP Protocol Support: Full integration with Claude and other AI assistants
• 🚀 Multiple Deployment Options: Deploy to Vercel, Railway, Render, or self-host
• 🛡️ Enterprise Security: Auth0, OAuth 2.0, API key authentication, and rate limiting
• 📊 Complete Figma API Coverage: All major Figma operations accessible via MCP tools
• 🔄 Real-time Updates: WebSocket support for live collaboration features
• 📦 TypeScript SDK: Fully typed client SDK for Node.js applications
• 📚 Comprehensive Documentation: Detailed API reference, integration guides, and examples

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Figma account with personal access token or OAuth app
• PostgreSQL database (required for OAuth, optional for API key auth)
• (Optional) Redis for rate limiting

Installation

# Clone the repository
git clone https://github.com/haseebrj17/figma-mcp-server.git
cd figma-mcp-server

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Set up database (interactive setup wizard)
npm run setup:db

# Or manually configure .env and run:
# npm run prisma:generate
# npm run prisma:migrate

# Start development server
npm run dev

🔧 Configuration

Environment Variables

Create a .env file based on .env.example:

# Server Configuration
NODE_ENV=development
PORT=3000
SERVER_URL=http://localhost:3000

# Authentication Method (choose one)
AUTH_METHOD=oauth  # Options: 'oauth', 'apikey', 'auth0'

# Figma OAuth (recommended for production)
FIGMA_CLIENT_ID=your-figma-client-id
FIGMA_CLIENT_SECRET=your-figma-client-secret
FIGMA_REDIRECT_URI=http://localhost:3000/auth/callback

# OR Figma Personal Token (for development)
FIGMA_ACCESS_TOKEN=your-personal-access-token

# Database (required for OAuth)
DATABASE_URL=postgresql://user:password@localhost:5432/figma_mcp

# Optional: Redis for rate limiting
REDIS_URL=redis://localhost:6379

# Optional: Monitoring
SENTRY_DSN=your-sentry-dsn

Authentication Methods

1. OAuth with Auto-Refresh (Recommended)

Implements Figma OAuth 2.0 with automatic token refresh:

// Tokens are automatically refreshed before expiry
// No manual intervention needed

2. API Key Authentication

Simple key-based auth for server-to-server:

AUTH_METHOD=apikey
API_KEY=your-secure-api-key

3. Auth0 Integration

Enterprise SSO with Auth0:

AUTH_METHOD=auth0
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-secret

📚 Available MCP Tools

The server exposes these Figma operations as MCP tools:

| Tool | Description | Parameters | |------|-------------|------------| | get_file | Retrieve complete file data | fileKey, branch_data, version, depth | | get_file_nodes | Get specific nodes from a file | fileKey, nodeIds, version, depth | | get_file_images | Export images from nodes | fileKey, nodeIds, format, scale | | get_file_styles | Get all styles in a file | fileKey | | get_file_components | Get all components | fileKey | | get_team_projects | List team projects | teamId | | get_project_files | List files in a project | projectId | | get_file_comments | Get file comments | fileKey | | post_file_comment | Post a new comment | fileKey, message, client_meta | | get_file_versions | Get version history | fileKey |

Example Usage with Claude

// In Claude or any MCP client
const result = await mcp.callTool('get_file', {
  fileKey: 'abc123xyz',
  depth: 2
});

// Export images from specific nodes
const images = await mcp.callTool('get_file_images', {
  fileKey: 'abc123xyz',
  nodeIds: ['1:2', '3:4'],
  format: 'png',
  scale: 2
});

🖥️ Client SDK

Installation

npm install figma-mcp-client

Usage

import { FigmaMCPClient } from 'figma-mcp-client';

// Initialize client
const client = new FigmaMCPClient({
  serverUrl: 'https://your-server.vercel.app',
  apiKey: 'your-api-key',
  transport: 'http' // or 'websocket'
});

// Connect to server
await client.connect();

// Use Figma tools
const file = await client.getFile('your-file-key');
const components = await client.getComponents('your-file-key');

// Export images
const images = await client.exportImages('your-file-key', ['node-id-1', 'node-id-2'], {
  format: 'png',
  scale: 2
});

🌐 API Endpoints

MCP Protocol Endpoints

GET /mcp/tools
Authorization: Bearer <token>

POST /mcp/tools/call
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "get_file",
  "arguments": {
    "fileKey": "abc123xyz"
  }
}

REST API Endpoints

GET /api/files/:fileKey
GET /api/files/:fileKey/nodes?ids=1:2,3:4
GET /api/files/:fileKey/images?ids=1:2&format=png&scale=2
GET /api/files/:fileKey/styles
GET /api/files/:fileKey/components
GET /api/teams/:teamId/projects
GET /api/projects/:projectId/files
GET /api/files/:fileKey/comments
POST /api/files/:fileKey/comments
GET /api/files/:fileKey/versions

OAuth Endpoints

GET /auth/figma                 # Start OAuth flow
GET /auth/callback              # OAuth callback
POST /auth/refresh              # Refresh access token
GET /auth/status                # Check auth status
POST /auth/logout               # Logout user

🚢 Deployment

Deploy to Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Deploy to Railway

1. Click "Deploy on Railway"
2. Configure environment variables
3. Deploy

Deploy to Render

1. Click "Deploy to Render"
2. Configure build and start commands:
   • Build: npm run build
   • Start: npm run start

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
RUN npm run prisma:generate
EXPOSE 3000
CMD ["npm", "start"]

docker build -t figma-mcp-server .
docker run -p 3000:3000 --env-file .env figma-mcp-server

🛠️ Development

Available Scripts

npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run start        # Run production server
npm run test         # Run test suite
npm run lint         # Lint code with ESLint
npm run typecheck    # Type check with TypeScript

# Database commands
npm run setup:db         # Interactive database setup wizard
npm run prisma:generate  # Generate Prisma client
npm run prisma:migrate   # Run migrations (dev)
npm run prisma:deploy    # Deploy migrations (prod)
npm run prisma:studio    # Open Prisma Studio GUI
node test-db-connection.js # Test database connection

# Deployment
npm run vercel-build     # Build for Vercel

Project Structure

figma-mcp-server/
├── src/
│   ├── index.ts           # Main MCP server entry
│   ├── http-server.ts     # Express HTTP server
│   ├── services/
│   │   ├── auth.ts        # Authentication service
│   │   ├── figma.ts       # Figma API wrapper
│   │   ├── oauth.ts       # OAuth implementation
│   │   └── prisma.ts      # Database client
│   ├── routes/
│   │   └── oauth.ts       # OAuth routes
│   └── types/
│       └── figma.ts       # Type definitions
├── client-sdk/            # TypeScript SDK
│   ├── src/
│   └── examples/
├── docs/                  # Documentation
│   ├── QUICKSTART.md      # Quick start guide
│   ├── API_REFERENCE.md   # Complete API documentation
│   ├── INTEGRATION_GUIDE.md # Platform integrations
│   ├── EXAMPLES.md        # Code examples
│   ├── DEPLOYMENT.md      # Deployment guide
│   └── MIGRATION_GUIDE.md # Migration guide
├── prisma/
│   └── schema.prisma      # Database schema
├── tests/                 # Test files
├── .env.example          # Environment template
├── CLAUDE.md             # AI assistant instructions
└── README.md             # This file

🔒 Security

Best Practices

• ✅ Never commit tokens: Use environment variables
• ✅ Use OAuth in production: Automatic token refresh prevents expiry
• ✅ Enable rate limiting: Protect against abuse
• ✅ Validate inputs: All inputs are validated with Zod schemas
• ✅ Use HTTPS: Always use SSL in production
• ✅ Implement CSP: Content Security Policy headers included
• ✅ Regular updates: Keep dependencies updated

Rate Limiting

// Built-in rate limiting per user
const rateLimiter = {
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each user to 100 requests per window
};

📖 Documentation

Comprehensive Documentation

The project includes extensive documentation to help you integrate and use the Figma MCP Server:

• Quick Start Guide - Get up and running in under 5 minutes
• API Reference - Complete API documentation with all endpoints, parameters, and examples
• Integration Guide - Step-by-step guides for integrating with Claude, LangChain, OpenAI, and more
• Examples - Full code examples for common use cases and complete applications
• Deployment Guide - Deploy to Vercel, Railway, Render, or self-host
• Migration Guide - Migrate from personal tokens to OAuth
• Database Setup - PostgreSQL setup with Prisma ORM

Quick Links

• Base URL: https://figma-mcp-server-nu.vercel.app
• Health Check: GET /api/health
• List Tools: GET /api/mcp/tools
• Execute Tool: POST /api/mcp/tools/call

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🐛 Troubleshooting

Common Issues

Token Expiry

• Solution: Enable OAuth with auto-refresh
• Temporary: Update FIGMA_ACCESS_TOKEN in .env

Database Connection Failed

• Check DATABASE_URL format
• Ensure PostgreSQL is running
• Run migrations: npm run prisma:migrate

Rate Limiting

• Configure Redis for distributed rate limiting
• Adjust limits in rateLimiter config

CORS Issues

• Add your domain to ALLOWED_ORIGINS
• Check Access-Control-Allow-Origin headers

📄 License

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

🙏 Acknowledgments

• Figma API for the excellent API
• Model Context Protocol for the MCP specification
• Anthropic for Claude and MCP SDK
• All contributors and users of this project

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📚 Docs: Documentation

---

<p align="center"> Made with ❤️ by Muhammad Haseeb </p> <p align="center"> <a href="https://github.com/haseebrj17/figma-mcp-server">GitHub</a> • <a href="https://www.npmjs.com/package/figma-mcp-server">NPM</a> • <a href="https://github.com/haseebrj17/figma-mcp-server/tree/main/docs">Documentation</a> </p>