Figma MCP Server

Permite que assistentes de IA interajam com o Figma via WebSocket para leitura de dados e análise de design.

Documentação

Figma MCP Server (Python)

Servidor Figma Model Context Protocol (MCP), implementado em Python usando FastMCP. Este servidor permite que assistentes de IA interajam com o Figma através de uma conexão WebSocket para leitura de dados e análise de designs.

🎯 Recursos

📖 Leitura de dados: Obtenção de informações sobre documentos, nós, componentes e estilos
🔍 Busca e análise: Varredura de nós por tipos, busca de conteúdo textual
📤 Exportação: Exportação de nós como imagens em vários formatos
📋 Anotações: Visualização de anotações em documentos
🧩 Componentes: Trabalho com componentes e suas instâncias
🔗 Prototipagem: Obtenção de informações sobre reações e conexões

🚫 Limitações

Por segurança, este servidor NÃO suporta:

Criação de novos elementos
Alteração de estilos, cores ou texto (ferramentas set_*)
Operações de modificação de nós (mover, redimensionar, excluir, clonar)

📋 Ferramentas disponíveis (15 itens)

🔗 Conexão

join_channel - Entrar em um canal para comunicação com o Figma

📖 Obtenção de informações

get_document_info - Obter informações sobre o documento Figma atual
get_selection - Obter informações sobre a seleção atual
read_my_design - Obter informações detalhadas sobre a seleção, incluindo todos os detalhes dos nós
get_node_info - Obter informações sobre um nó específico por ID
get_nodes_info - Obter informações sobre vários nós
get_node_children - Obter IDs de todos os nós filhos com aninhamento recursivo completo
get_styles - Obter todos os estilos do documento
get_local_components - Obter todos os componentes locais

🧩 Componentes

get_instance_overrides - Obter substituições de instância de componente

🔍 Busca e varredura

scan_text_nodes - Escanear nós de texto dentro de um nó especificado
scan_nodes_by_types - Escanear nós de tipos específicos (TEXT, RECTANGLE, FRAME)

📤 Exportação

export_node_as_image - Exportar um nó como imagem (PNG, JPG, SVG, PDF)

📋 Anotações

get_annotations - Obter anotações para um nó ou para o documento inteiro

🔗 Prototipagem

get_reactions - Obter reações (conexões interativas) para nós

🏗️ Arquitetura

AI Client (Cursor) ←→ MCP Server ←→ WebSocket Server ←→ Figma Plugin

MCP Server - Fornece ferramentas para IA
WebSocket Server - Coordena conexões e canais
Figma Plugin - Executa comandos no Figma

🚀 Início rápido

1. Instalação de dependências

cd python-version
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или venv\Scripts\activate  # Windows
pip install -r requirements.txt

2. Iniciando o servidor WebSocket

python websocket_proxy.py --port 3055 --debug

3. Executando no Figma

Abra o Figma Desktop
Vá em Plugins → Development → Import plugin from manifest...
Selecione src/cursor_mcp_plugin/manifest.json
Execute o plugin "Cursor MCP Plugin"
Conecte-se ao servidor na porta 3055
Anote o Channel ID (por exemplo: abc123xyz)

4. Configuração do MCP no Cursor

Adicione a seguinte configuração nas configurações MCP do Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "figma-mcp": {
      "command": "python",
      "args": ["-m", "src.figma_mcp.server", "--server", "localhost:3055"],
      "cwd": "/path/to/your/figma_mcp"
    }
  }
}

Método alternativo (com ambiente virtual):

{
  "mcpServers": {
    "figma-mcp": {
      "command": "/path/to/your/figma_mcp/venv/bin/python",
      "args": ["/path/to/your/figma_mcp/src/figma_mcp/server.py", "--server", "localhost:3055"]
    }
  }
}

Nota: Substitua /path/to/your/figma_mcp pelo caminho real do projeto.

5. Iniciando o servidor MCP

python -m src.figma_mcp.server --server localhost:3055

6. Conectando-se ao canal

Use a ferramenta join_channel com o Channel ID obtido:

{
  "tool": "join_channel",
  "arguments": {
    "channel": "abc123xyz"
  }
}

🛠️ Exemplos de uso

Obtendo informações do documento

{
  "tool": "get_document_info",
  "arguments": {}
}

Obtendo informações de um nó

{
  "tool": "get_node_info", 
  "arguments": {
    "node_id": "4472:98013"
  }
}

Obtendo todos os nós filhos

{
  "tool": "get_node_children",
  "arguments": {
    "node_id": "4472:98012"
  }
}

Buscando nós de texto

{
  "tool": "scan_text_nodes",
  "arguments": {
    "node_id": "4472:98012",
    "use_chunking": true,
    "chunk_size": 50
  }
}

Exportando como imagem

{
  "tool": "export_node_as_image",
  "arguments": {
    "node_id": "4472:98013",
    "format": "PNG",
    "scale": 2.0
  }
}

🔧 Configuração

WebSocket Server

Porta: 3055 (padrão)
Host: localhost
Modo debug: --debug

MCP Server

Server URL: localhost:3055 (padrão)
Protocolo: MCP 2024-11-05
Transport: stdio

Cursor MCP Settings

Crie o arquivo .cursor/mcp.json na raiz do seu projeto ou no diretório pessoal:

{
  "$schema": "https://schema.cursor.com/mcp.json",
  "mcpServers": {
    "figma-mcp": {
      "command": "python",
      "args": ["-m", "src.figma_mcp.server", "--server", "localhost:3055"],
      "cwd": "/absolute/path/to/figma_mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/figma_mcp"
      }
    }
  }
}

Parâmetros principais:

command: Comando para executar Python
args: Argumentos para iniciar o servidor MCP
cwd: Diretório de trabalho (caminho absoluto do projeto)
env: Variáveis de ambiente (opcional)

📁 Estrutura do projeto

python-version/
├── src/figma_mcp/
│   ├── __init__.py
│   ├── server.py          # Главный MCP сервер
│   ├── websocket_client.py # WebSocket клиент
│   ├── types.py           # Типы Pydantic
│   └── utils.py           # Утилиты
├── tests/                 # Тесты (41 тест)
├── websocket_proxy.py     # WebSocket сервер
├── requirements.txt       # Зависимости
└── README.md             # Документация

🧪 Testes

Executar todos os testes:

python -m pytest tests/ -v

Teste de conexão:

python test_mcp.py

🔒 Segurança

Filtragem de dados confidenciais das respostas do Figma
Validação de todos os parâmetros com Pydantic
Tratamento de erros e timeouts
Registro de logs em stderr para depuração

📦 Dependências

fastmcp: 2.4.0 - Framework de servidor MCP
websockets: 15.0.1 - Cliente/servidor WebSocket
pydantic: 2.11.5 - Validação de dados
pytest: 8.3.5 - Testes

🐛 Depuração

Problemas de conexão: Verifique o status do servidor WebSocket
Timeouts: Aumente o timeout no cliente WebSocket
Erros de canal: Certifique-se de estar usando o Channel ID correto
Logs: Consulte a saída em stderr para informações detalhadas

📝 Licença

MIT License

🤝 Contribuição

Faça um fork do repositório
Crie uma branch para a funcionalidade
Adicione testes
Envie um pull request