Figma MCP Server

Fornece acesso somente leitura a arquivos e projetos do Figma usando a API do Figma.

GitHub
150
Experimente este MCPPatrocinado

Documentação

Figma MCP Server

Um servidor Model Context Protocol (MCP) que fornece integração com a API do Figma por meio do Claude e outros clientes compatíveis com MCP. Atualmente suporta acesso somente leitura a arquivos e projetos do Figma, com arquitetura no lado do servidor capaz de suportar recursos mais avançados de gerenciamento de design tokens e temas (aguardando melhorias na API do Figma ou desenvolvimento de plugins).

Status do Projeto

Progresso Atual

  • ✅ Implementação Principal: Servidor TypeScript construído com sucesso seguindo o Model Context Protocol (MCP)
  • ✅ Integração com Claude Desktop: Testado e funcional com Claude Desktop
  • ✅ Operações de Leitura: Ferramentas get-file e list-files funcionando para acesso a arquivos do Figma
  • ✅ Arquitetura do Servidor: Sistema de cache, tratamento de erros e monitoramento de estatísticas implementados
  • ✅ Protocolos de Transporte: Mecanismos de transporte stdio e SSE suportados

Funcionalidade Completa Potencial

O servidor foi projetado com código para suportar esses recursos (atualmente limitados por restrições da API):

  • Gerenciamento de Variáveis: Criar, ler, atualizar e excluir design tokens (variáveis)
  • Tratamento de Referências: Criar e validar relacionamentos entre tokens
  • Gerenciamento de Temas: Criar temas com múltiplos modos (ex.: claro/escuro)
  • Análise de Dependências: Detectar e prevenir referências circulares
  • Operações em Lote: Executar ações em massa em variáveis e temas

Com o desenvolvimento de plugins do Figma ou acesso expandido à API, esses recursos poderiam ser totalmente habilitados.

Recursos

  • 🔑 Autenticação segura com a API do Figma
  • 📁 Operações de arquivo (ler, listar)
  • 🎨 Gerenciamento de sistema de design
    • Criação e gerenciamento de variáveis
    • Criação e configuração de temas
    • Tratamento e validação de referências
  • 🚀 Desempenho otimizado
    • Cache LRU
    • Tratamento de limite de taxa
    • Pool de conexões
  • 📊 Monitoramento abrangente
    • Verificações de saúde
    • Estatísticas de uso
    • Rastreamento de erros

Pré-requisitos

  • Node.js 18.x ou superior
  • Token de acesso do Figma com permissões apropriadas
  • Compreensão básica de MCP (Model Context Protocol)

Instalação

npm install figma-mcp-server

Configuração

  1. Crie um arquivo .env com base em .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 integração com Claude Desktop:

O servidor pode ser configurado no arquivo de configuração do 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:

  • Use caminhos ABSOLUTOS, não caminhos relativos
  • No Windows, use barras invertidas duplas (\\) nos caminhos
  • Reinicie o Claude Desktop após fazer alterações na configuração

Uso

Uso Básico

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

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

Ferramentas Disponíveis

  1. get-file

    • Recuperar detalhes do arquivo do Figma
    {
  "name": "get-file",
  "arguments": {
    "fileKey": "your_file_key"
  }
}

  2. list-files

    • Listar arquivos em um projeto do Figma
    {
  "name": "list-files",
  "arguments": {
    "projectId": "your_project_id"
  }
}

  3. create-variables

    • Criar variáveis de sistema de design
    {
  "name": "create-variables",
  "arguments": {
    "fileKey": "your_file_key",
    "variables": [
      {
        "name": "primary-color",
        "type": "COLOR",
        "value": "#0066FF"
      }
    ]
  }
}

  4. create-theme

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

Documentação da API

Métodos do Servidor

  • startServer(figmaToken: string, debug?: boolean, port?: number)
    • Inicializa e inicia o servidor MCP
    • Retorna: Promise

Esquemas de Ferramentas

Todas as entradas de ferramentas são validadas usando 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'])
  }))
});

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas e códigos de erro apropriados:

  • Token inválido: 403 com mensagem de erro específica
  • Limite de taxa: 429 com tempo de redefinição
  • Erros de validação: 400 com detalhes específicos do campo
  • Erros do servidor: 500 com rastreamento de erros

Limitações e Problemas Conhecidos

Restrições da API

  1. Operações Somente Leitura

    • Limitado a operações somente leitura devido a restrições da API do Figma
    • Tokens de acesso pessoal suportam apenas operações de leitura, não de escrita
    • Não é possível modificar variáveis, componentes ou estilos através da API REST com tokens pessoais
    • Operações de escrita exigiriam desenvolvimento de plugins do Figma

  2. Limite de Taxa

    • Segue os limites de taxa da API do Figma
    • Implemente backoff exponencial para melhor tratamento

  3. Gerenciamento de Cache

    • TTL padrão de 5 minutos
    • Limitado a 500 entradas
    • Considere implementar ganchos de invalidação de cache

  4. Autenticação

    • Suporta apenas tokens de acesso pessoal
    • Sem suporte para permissões de nível de equipe ou edição colaborativa
    • Implementação OAuth planejada para o futuro

  5. Implementação Técnica

    • Requer caminhos absolutos na configuração
    • Deve compilar arquivos TypeScript antes da execução
    • Requer lidar com resolução de módulos local e global

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações com testes
  4. Envie um pull request

Por favor, siga nossos padrões de codificação:

  • Modo estrito do TypeScript
  • Configuração ESLint
  • Jest para testes
  • Tratamento abrangente de erros

Licença

Licença MIT - Consulte o arquivo LICENSE para detalhes

Solução de Problemas

Consulte TROUBLESHOOTING.md para um guia abrangente de solução de problemas.

Problemas Comuns

  1. Erros de Conexão JSON

    • Use caminhos absolutos na configuração do Claude Desktop
    • Garanta que o servidor esteja compilado (npm run build)
    • Verifique se todas as variáveis de ambiente estão definidas

  2. Problemas de Autenticação

    • Verifique se o seu token de acesso do Figma é válido
    • Verifique se o token tem as permissões necessárias
    • Garanta que o token esteja corretamente definido na configuração

  3. Servidor Não Iniciando

    • Verifique a versão do Node.js (18.x+ necessário)
    • Verifique se o build existe (dist/index.js)
    • Verifique os logs do Claude Desktop:
      • macOS: ~/Library/Logs/Claude/mcp*.log
      • Windows: %APPDATA%\Claude\logs\mcp*.log

Para etapas e soluções de depuração mais detalhadas, consulte o guia de solução de problemas.

Suporte