Figma MCP Server

Proporciona acceso de solo lectura a archivos y proyectos de Figma mediante la API de Figma.

GitHub
150
Prueba este MCPPatrocinado

Documentación

Figma MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona integración con la API de Figma a través de Claude y otros clientes compatibles con MCP. Actualmente admite acceso de solo lectura a archivos y proyectos de Figma, con una arquitectura de servidor capaz de soportar funciones más avanzadas de gestión de tokens de diseño y temas (pendiente de mejoras en la API de Figma o desarrollo de plugins).

Estado del Proyecto

Progreso Actual

  • ✅ Implementación Principal: Se construyó exitosamente un servidor TypeScript siguiendo el Model Context Protocol (MCP)
  • ✅ Integración con Claude Desktop: Probado y funcional con Claude Desktop
  • ✅ Operaciones de Lectura: Funcionando las herramientas get-file y list-files para acceso a archivos de Figma
  • ✅ Arquitectura del Servidor: Sistema de caché, manejo de errores y monitoreo de estadísticas implementados
  • ✅ Protocolos de Transporte: Ambos mecanismos de transporte stdio y SSE soportados

Funcionalidad Completa Potencial

El servidor ha sido diseñado con código para soportar estas funciones (actualmente limitadas por restricciones de la API):

  • Gestión de Variables: Crear, leer, actualizar y eliminar tokens de diseño (variables)
  • Manejo de Referencias: Crear y validar relaciones entre tokens
  • Gestión de Temas: Crear temas con múltiples modos (por ejemplo, claro/oscuro)
  • Análisis de Dependencias: Detectar y prevenir referencias circulares
  • Operaciones por Lote: Realizar acciones masivas sobre variables y temas

Con el desarrollo de plugins de Figma o un acceso ampliado a la API, estas funciones podrían habilitarse por completo.

Características

  • 🔑 Autenticación segura con la API de Figma
  • 📁 Operaciones de archivos (leer, listar)
  • 🎨 Gestión del sistema de diseño
    • Creación y gestión de variables
    • Creación y configuración de temas
    • Manejo y validación de referencias
  • 🚀 Rendimiento optimizado
    • Caché LRU
    • Manejo de límites de tasa
    • Agrupación de conexiones
  • 📊 Monitoreo integral
    • Verificaciones de salud
    • Estadísticas de uso
    • Seguimiento de errores

Requisitos Previos

  • Node.js 18.x o superior
  • Token de acceso de Figma con permisos apropiados
  • Conocimiento básico de MCP (Model Context Protocol)

Instalación

npm install figma-mcp-server

Configuración

  1. Crea un archivo .env basado en .env.example:
# Figma API Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
DEBUG=figma-mcp:*
  1. Para la integración con Claude Desktop:

El servidor se puede configurar en tu archivo de configuración de Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-mcp-server/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Notas Importantes:

  • Usa rutas ABSOLUTAS, no rutas relativas
  • En Windows, usa dobles barras invertidas (\\) en las rutas
  • Reinicia Claude Desktop después de realizar cambios en la configuración

Uso

Uso Básico

import { startServer } from 'figma-mcp-server';

const server = await startServer(process.env.FIGMA_ACCESS_TOKEN);

Herramientas Disponibles

  1. get-file

    • Recuperar detalles del archivo de Figma
    {
  "name": "get-file",
  "arguments": {
    "fileKey": "your_file_key"
  }
}

  2. list-files

    • Listar archivos en un proyecto de Figma
    {
  "name": "list-files",
  "arguments": {
    "projectId": "your_project_id"
  }
}

  3. create-variables

    • Crear variables del sistema de diseño
    {
  "name": "create-variables",
  "arguments": {
    "fileKey": "your_file_key",
    "variables": [
      {
        "name": "primary-color",
        "type": "COLOR",
        "value": "#0066FF"
      }
    ]
  }
}

  4. create-theme

    • Crear y configurar temas
    {
  "name": "create-theme",
  "arguments": {
    "fileKey": "your_file_key",
    "name": "Dark Theme",
    "modes": [
      {
        "name": "dark",
        "variables": [
          {
            "variableId": "123",
            "value": "#000000"
          }
        ]
      }
    ]
  }
}

Documentación de la API

Métodos del Servidor

  • startServer(figmaToken: string, debug?: boolean, port?: number)
    • Inicializa y arranca el servidor MCP
    • Devuelve: Promise

Esquemas de Herramientas

Todas las entradas de las herramientas se validan mediante esquemas Zod:

const CreateVariablesSchema = z.object({
  fileKey: z.string(),
  variables: z.array(z.object({
    name: z.string(),
    type: z.enum(['COLOR', 'FLOAT', 'STRING']),
    value: z.string(),
    scope: z.enum(['LOCAL', 'ALL_FRAMES'])
  }))
});

Manejo de Errores

El servidor proporciona mensajes de error detallados y códigos de error apropiados:

  • Token no válido: 403 con mensaje de error específico
  • Límite de tasa: 429 con tiempo de reinicio
  • Errores de validación: 400 con detalles específicos del campo
  • Errores del servidor: 500 con seguimiento de errores

Limitaciones y Problemas Conocidos

Restricciones de la API

  1. Operaciones de Solo Lectura

    • Limitado a operaciones de solo lectura debido a restricciones de la API de Figma
    • Los tokens de acceso personal solo admiten operaciones de lectura, no de escritura
    • No se pueden modificar variables, componentes o estilos a través de la API REST con tokens personales
    • Las operaciones de escritura requerirían en su lugar el desarrollo de un plugin de Figma

  2. Límite de Tasa

    • Sigue los límites de tasa de la API de Figma
    • Implementa retroceso exponencial para un mejor manejo

  3. Gestión de Caché

    • TTL predeterminado de 5 minutos
    • Limitado a 500 entradas
    • Considera implementar enlaces de invalidación de caché

  4. Autenticación

    • Solo admite tokens de acceso personal
    • Sin soporte para permisos a nivel de equipo o edición colaborativa
    • Implementación de OAuth planificada para el futuro

  5. Implementación Técnica

    • Requiere rutas absolutas en la configuración
    • Debe compilar archivos TypeScript antes de la ejecución
    • Requiere manejar la resolución de módulos tanto local como global

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios con pruebas
  4. Envía un pull request

Por favor, sigue nuestros estándares de codificación:

  • Modo estricto de TypeScript
  • Configuración de ESLint
  • Jest para pruebas
  • Manejo integral de errores

Licencia

Licencia MIT - Consulta el archivo LICENSE para más detalles

Solución de Problemas

Consulta TROUBLESHOOTING.md para obtener una guía completa de solución de problemas.

Problemas Comunes

  1. Errores de Conexión JSON

    • Usa rutas absolutas en la configuración de Claude Desktop
    • Asegúrate de que el servidor esté compilado (npm run build)
    • Verifica que todas las variables de entorno estén configuradas

  2. Problemas de Autenticación

    • Verifica que tu token de acceso de Figma sea válido
    • Comprueba que el token tenga los permisos necesarios
    • Asegúrate de que el token esté configurado correctamente

  3. El Servidor No Se Inicia

    • Verifica la versión de Node.js (se requiere 18.x o superior)
    • Verifica que la compilación exista (dist/index.js)
    • Revisa los registros de Claude Desktop:
      • macOS: ~/Library/Logs/Claude/mcp*.log
      • Windows: %APPDATA%\Claude\logs\mcp*.log

Para pasos de depuración y soluciones más detallados, consulta la guía de solución de problemas.

Soporte