wyvern800/mcp-figma

Figma MCP Server

Servidor MCP (Model Context Protocol) para integração com a API do Figma. Permite exportar arquivos, páginas, componentes, nodes e imagens do Figma através de ferramentas MCP.

📋 Índice

• Pré-requisitos
• Instalação
• Configuração
• Uso
• Ferramentas Disponíveis
• Estrutura do Projeto
• Desenvolvimento
• Troubleshooting

🔧 Pré-requisitos

• Node.js 18+
• npm ou yarn
• TypeScript 5.0+
• Token de acesso da API do Figma

Como obter o Token do Figma

1. Acesse Figma
2. Vá em Settings → Account → Personal Access Tokens
3. Clique em Create new token
4. Copie o token gerado (você só verá ele uma vez!)

📦 Instalação

1. Clone o repositório:

git clone <repository-url>
cd mcp-figma

2. Instale as dependências:

npm install
# ou
yarn install

3. Compile o projeto:

npm run build
# ou
yarn build

4. Configure seu token do Figma (veja seção Configuração)

⚙️ Configuração

Opção 1: Variável de Ambiente (Recomendado)

Configure a variável de ambiente FIGMA_API_TOKEN:

Windows (PowerShell):

$env:FIGMA_API_TOKEN = "seu-token-figma"

Windows (CMD):

set FIGMA_API_TOKEN=seu-token-figma

Linux/Mac:

export FIGMA_API_TOKEN="seu-token-figma"

Para tornar permanente no Windows:

1. Abra Variáveis de Ambiente do sistema
2. Adicione FIGMA_API_TOKEN nas variáveis de usuário ou sistema

Opção 2: Configuração no Cursor

1. Copie o arquivo de exemplo:

cp .cursordev/settings.json.example .cursordev/settings.json

2. Edite o arquivo .cursordev/settings.json ou ~/.cursor/mcp.json:

{
  "mcpServers": {
    "FigmaMCP": {
      "command": "node",
      "args": ["/caminho/absoluto/para/seu/projeto/mcp-figma/dist/index.js"],
      "env": {
        "FIGMA_API_TOKEN": "seu-token-figma-aqui"
      }
    }
  }
}

Nota:

• Ajuste o caminho args para o caminho absoluto do seu projeto
• O arquivo .cursordev/settings.json está no .gitignore e não será commitado
• Use o arquivo .cursordev/settings.json.example como referência

🚀 Uso

Iniciar o Servidor

npm start
# ou
yarn start

O servidor MCP roda via stdio e aguarda requisições do cliente MCP.

Usar no Cursor/Claude Desktop

Após configurar o servidor MCP, você pode usar as ferramentas diretamente:

@FigmaMCP exportFullFile fileId="seu-file-id"

Ou com token explícito:

@FigmaMCP exportFullFile fileId="seu-file-id" token="seu-token"

🛠️ Ferramentas Disponíveis

1. exportFullFile

Exporta o arquivo completo do Figma.

Parâmetros:

• fileId (obrigatório): ID do arquivo do Figma
• token (opcional): Token da API do Figma (se não estiver na env var)

Exemplo:

@FigmaMCP exportFullFile fileId="abc123xyz"

2. exportPages

Exporta todas as páginas de um arquivo do Figma.

Parâmetros:

• fileId (obrigatório): ID do arquivo do Figma
• token (opcional): Token da API do Figma

Exemplo:

@FigmaMCP exportPages fileId="abc123xyz"

3. exportPageFrames

Exporta os frames de uma página específica.

Parâmetros:

• fileId (obrigatório): ID do arquivo do Figma
• pageName (obrigatório): Nome da página
• token (opcional): Token da API do Figma

Exemplo:

@FigmaMCP exportPageFrames fileId="abc123xyz" pageName="Home"

4. exportComponents

Exporta todos os componentes de um arquivo do Figma.

Parâmetros:

• fileId (obrigatório): ID do arquivo do Figma
• token (opcional): Token da API do Figma

Exemplo:

@FigmaMCP exportComponents fileId="abc123xyz"

5. exportNodes

Exporta nodes específicos de um arquivo do Figma.

Parâmetros:

• fileId (obrigatório): ID do arquivo do Figma
• ids (obrigatório): Array de IDs dos nodes
• token (opcional): Token da API do Figma

Exemplo:

@FigmaMCP exportNodes fileId="abc123xyz" ids=["node1", "node2"]

6. exportImages

Exporta imagens de nodes específicos.

Parâmetros:

• fileId (obrigatório): ID do arquivo do Figma
• ids (obrigatório): Array de IDs dos nodes
• token (opcional): Token da API do Figma

Exemplo:

@FigmaMCP exportImages fileId="abc123xyz" ids=["node1", "node2"]

7. exportTokens

Retorna informações sobre design tokens (extração manual).

Parâmetros:

• Nenhum

Exemplo:

@FigmaMCP exportTokens

📁 Estrutura do Projeto

mcp-figma/
├── src/
│   ├── api/
│   │   └── figmaClient.ts      # Cliente para API do Figma
│   ├── handlers/
│   │   ├── exportFullFile.ts   # Handler para exportar arquivo completo
│   │   ├── exportPages.ts      # Handler para exportar páginas
│   │   ├── exportPageFrames.ts  # Handler para exportar frames
│   │   ├── exportComponents.ts # Handler para exportar componentes
│   │   ├── exportNodes.ts      # Handler para exportar nodes
│   │   ├── exportImages.ts     # Handler para exportar imagens
│   │   └── exportTokens.ts    # Handler para exportar tokens
│   ├── mcp/
│   │   ├── registry.ts         # Registro do servidor MCP
│   │   └── schema.ts           # Schema dos métodos MCP
│   ├── utils/
│   │   ├── logger.ts           # Utilitário de logging
│   │   └── parseNodes.ts       # Utilitário para parsing de nodes
│   └── index.ts                # Ponto de entrada do servidor
├── dist/                       # Código compilado (gerado)
├── package.json
├── tsconfig.json
└── README.md

💻 Desenvolvimento

Scripts Disponíveis

# Compilar TypeScript
npm run build

# Iniciar o servidor
npm start

Compilação

O projeto usa TypeScript e compila para ES2020 modules:

npm run build

Os arquivos compilados são gerados na pasta dist/.

Adicionar Nova Ferramenta

1. Crie o handler em src/handlers/:

import { FigmaClient } from "../api/figmaClient.js";

export async function exportNovaFerramenta(token: string, fileId: string) {
  const client = new FigmaClient(token);
  // Sua lógica aqui
  return result;
}

2. Adicione o import em src/index.ts:

import { exportNovaFerramenta } from "./handlers/exportNovaFerramenta.js";

3. Registre a ferramenta no ListToolsRequestSchema:

{
  name: "exportNovaFerramenta",
  description: "Descrição da ferramenta",
  inputSchema: {
    type: "object",
    properties: {
      token: { type: "string", description: "..." },
      fileId: { type: "string", description: "..." },
    },
    required: ["fileId"],
  },
}

4. Adicione o case no CallToolRequestSchema:

case "exportNovaFerramenta":
  result = await exportNovaFerramenta(token, params.fileId as string);
  break;

5. Recompile:

npm run build

🐛 Troubleshooting

Erro: "Cannot find module"

Problema: Módulos não encontrados após compilação.

Solução:

npm install
npm run build

Erro: "Figma API token is required"

Problema: Token não configurado.

Solução:

• Configure a variável de ambiente FIGMA_API_TOKEN
• Ou passe o token como parâmetro nas chamadas

Erro: "Unexpected token 'F'... is not valid JSON"

Problema: Logs sendo enviados para stdout, interferindo com JSON-RPC.

Solução: Já corrigido! Os logs agora vão para stderr. Se ainda ocorrer, verifique se não há console.log() no código.

Erro: "ERR_MODULE_NOT_FOUND"

Problema: Imports sem extensão .js.

Solução: Todos os imports relativos devem ter extensão .js:

import { algo } from "./arquivo.js"; // ✅ Correto
import { algo } from "./arquivo";    // ❌ Errado

Servidor não inicia

Problema: Erro ao iniciar o servidor.

Solução:

1. Verifique se compilou: npm run build
2. Verifique o caminho no settings.json
3. Verifique se o Node.js está instalado: node --version

Como encontrar o File ID do Figma

O File ID está na URL do arquivo do Figma:

https://www.figma.com/file/FILE_ID_HERE/nome-do-arquivo

Exemplo:

• URL: https://www.figma.com/file/abc123xyz/Meu-Design
• File ID: abc123xyz

📚 Recursos

• Documentação da API do Figma
• Model Context Protocol
• TypeScript Documentation

🔒 Segurança

IMPORTANTE: Nunca commite tokens ou informações sensíveis no repositório!

• O arquivo .cursordev/settings.json está no .gitignore e não será commitado
• Use variáveis de ambiente para tokens em produção
• Use o arquivo .cursordev/settings.json.example como referência
• Se você acidentalmente commitou um token, revogue-o imediatamente no Figma e gere um novo

📦 Publicação

Este projeto está pronto para ser compartilhado publicamente. Certifique-se de:

1. ✅ Não commitar tokens ou informações sensíveis
2. ✅ Ter o .gitignore configurado corretamente
3. ✅ Ter o README completo e atualizado
4. ✅ Ter exemplos de configuração sem tokens

📝 Licença

Este projeto está licenciado sob a .

Você é livre para usar, modificar e distribuir este software, desde que mantenha o aviso de copyright e a licença incluídos nos arquivos.

👥 Contribuindo

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📧 Contato

Discord: godzamy