Goxel MCP Server

📌 Visão Geral

O Goxel MCP Server expõe as capacidades de modelagem, escultura procedural e renderização do Goxel diretamente para modelos de linguagem (LLMs) e agentes autônomos.

Com este servidor, seu agente de IA pode:

• 🧙‍♂️ Gerar Personagens 3D Completos prontos em voxel (archer, tank, mage, support, elf_healer, cyberpunk_archer).

• ⚔️ Esculpir Armas e Objetos de Cenário (espadas, escudos, arcos, cajados, baús, tochas, poções, pilares).

• 📜 Executar Scripts Procedurais QuickJS personalizados diretamente no motor do Goxel.

• 🔄 Converter e Exportar modelos entre .vox (MagicaVoxel / Goxel), .obj (Wavefront 3D com texturas), .gltf e renders .png.

• 🖥️ Lançar a Interface Gráfica (GUI) do Goxel instantaneamente na tela com o modelo carregado para inspeção ou edição humana.

Related MCP server: VoxelForge

🛠️ Ferramentas Disponíveis (MCP Tools)

⚙️ Pré-requisitos

1. Node.js (versão 18 ou superior instalada).

2. Goxel (versão 0.15+):

   • Linux: AppImage ou pacote nativo (goxel).

   • macOS: brew install goxel ou o binário do app.

   • Windows: Executável goxel.exe adicionado ao PATH.

🚀 Como Ativar e Configurar

1. Google Antigravity (Recomendado)

No Google Antigravity, você pode adicionar o servidor nas configurações de MCP ou no arquivo de manifesto do seu workspace / sistema:

Opção A — No arquivo de configuração MCP do Antigravity (mcp_config.json ou settings.json):

{
  "mcpServers": {
    "goxel": {
      "command": "node",
      "args": ["/caminho/para/goxel-mcp/server.js"],
      "env": {
        "GOXEL_BIN": "/caminho/para/goxel",
        "GOXEL_OUTPUT_DIR": "/caminho/para/seus/modelos"
      }
    }
  }
}

Opção B — Configuração Direta Local: Se você já possui o Goxel e o repositório clonado localmente:

{
  "mcpServers": {
    "goxel": {
      "command": "node",
      "args": ["/media/alex/alex/pro_unity/mcp-servers/goxel/server.js"]
    }
  }
}

2. OpenCode

No OpenCode, adicione o MCP ao seu arquivo opencode.json ou nas configurações de extensões MCP do editor:

{
  "mcp": {
    "servers": {
      "goxel": {
        "type": "stdio",
        "command": "node",
        "args": ["/caminho/absoluto/para/goxel-mcp/server.js"],
        "env": {
          "GOXEL_BIN": "goxel"
        }
      }
    }
  }
}

3. Claude Desktop

Abra o arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Adicione em mcpServers:

{
  "mcpServers": {
    "goxel": {
      "command": "node",
      "args": ["/caminho/absoluto/para/goxel-mcp/server.js"],
      "env": {
        "GOXEL_BIN": "/usr/bin/goxel",
        "GOXEL_OUTPUT_DIR": "/caminho/onde/salvar/modelos"
      }
    }
  }
}

4. Cursor / Windsurf / VS Code (Cline / Roo Code)

No seu editor preferido com suporte a MCP, configure o servidor padrão stdio:

{
  "goxel": {
    "command": "node",
    "args": ["/caminho/absoluto/para/goxel-mcp/server.js"]
  }
}

🌐 Variáveis de Ambiente Suportadas

💬 Exemplos de Prompts para o Agente de IA

Você pode conversar naturalmente com o seu modelo conectado ao MCP:

• "Crie um herói arqueiro em Voxel Art, exporte para .obj e abra na interface gráfica do Goxel para eu ver."

• "Gere um baú e uma espada em voxel e salve na pasta de assets do meu jogo."

• "Escreva um script procedural para o Goxel que gere uma torre espiral de 40 blocos de altura e exporte em .vox."

• "Converta o modelo character.vox para character.obj e renderize um preview em character.png."

🧱 Estrutura do Repositório

goxel-mcp/
├── assets/
│   └── goxel.png          # Ícone e apresentação visual do Goxel
├── server.js              # Servidor MCP stdio JSON-RPC 2.0 com suporte a tools
├── package.json           # Manifesto npm e dependências
├── LICENSE                # Licença MIT
└── README.md              # Documentação completa

🤝 Contribuições

Contribuições são super bem-vindas! Se você deseja adicionar novas classes de personagens procedurais, geradores de armas ou novos formatos de exportação:

1. Faça um Fork do projeto.

2. Crie uma branch para a sua feature (git checkout -b feature/novo-gerador).

3. Faça o commit de suas alterações (git commit -m 'Adiciona gerador de dragão voxel').

4. Abra um Pull Request.

📄 Licença

Distribuído sob a licença MIT. Consulte o arquivo LICENSE para obter mais informações.

Desenvolvido por Alex Sandro (al3x-d3v357).