Skip to main content
Glama
al3x-d3v357

Goxel MCP Server

by al3x-d3v357
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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)

Ferramenta

Descrição

Principais Parâmetros

goxel_create_character

Constrói um personagem voxel humanoide com túnicas, armaduras, armas e paleta de cores.

character_class (enum: archer, tank, mage, support, etc.), export_obj, open_in_gui, output_dir

goxel_create_object

Constrói armas e itens de ambientação táticos/RPG.

object_type (enum: sword, shield, staff, bow, chest, potion, torch, pillar), output_path, export_obj, open_in_gui

goxel_run_custom_script

Executa código JavaScript procedural no motor interno QuickJS do Goxel para esculturas geométricas avançadas.

script_code (código JS com acesso a vol), output_vox_path

goxel_export_model

Converte um arquivo voxel para outros formatos 3D ou imagem.

input_file (.vox/.gox), output_file (.obj, .gltf, .png)

goxel_open_gui

Abre o executável do Goxel na interface gráfica com o modelo na tela.

file_path (caminho para .vox ou .gox)

⚙️ 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

Variável

Padrão

Descrição

GOXEL_BIN

goxel (ou detecção automática do AppImage local)

Caminho completo do executável ou AppImage do Goxel.

GOXEL_OUTPUT_DIR

./output_voxels (ou pasta Unity detectada)

Diretório padrão onde personagens e objetos gerados serão armazenados.

DISPLAY

:0

Variável de ambiente do X11/Wayland para abrir a GUI na tela no Linux.

💬 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).

Available Tools

5 tools
goxel_create_characterC

Constrói um personagem em Voxel Art 3D (Arqueiro, Tanque, Mago, Suporte ou customizado) utilizando o Goxel e exporta para .vox e .obj.

NameRequiredDescriptionDefault
export_objNoSe verdadeiro, também converte e exporta o modelo para .obj 3D
output_dirNoDiretório onde salvar os arquivos gerados (opcional)
open_in_guiNoSe verdadeiro, abre a interface gráfica do Goxel com o personagem na tela
character_classYesClasse do herói a ser gerado

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations cover the behavior, so the description must carry the full burden. It states Goxel is used and .vox/.obj are produced, but omits whether Goxel must be installed, what happens on failure, whether files are overwritten, or that .obj export may be optional (the description implies .obj always, while export_obj is a flag).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that establishes purpose, resource, and outputs with zero filler. Slightly dense with the parenthetical class list, but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With four fully documented parameters and no output schema, the definition covers the minimum needed to invoke the tool. However, for an unannotated tool that touches the filesystem and possibly a GUI, the missing operational context (Goxel dependency, file overwrite behavior, .obj optionality) leaves real gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description only reinforces the character_class concept (listing classes) without adding meaning for output_dir, open_in_gui, or export_obj beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete verb (Constrói) and resource (personagem em Voxel Art 3D), lists the character classes, and states the export formats. This distinguishes it implicitly from goxel_create_object, but never names the sibling or explains the distinction explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use versus alternatives, no mention of when to prefer goxel_create_object, goxel_export_model, or goxel_open_gui. The context (creating a character) is implied but no exclusions or conditions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

goxel_create_objectB

Constrói um objeto, arma ou item de cenário em Voxel Art 3D (espada, escudo, cajado, arco, baú, poção, tocha, pilar).

NameRequiredDescriptionDefault
export_objNoSe verdadeiro, também exporta para .obj
object_typeYesTipo de objeto a ser modelado
open_in_guiNoSe verdadeiro, abre no Goxel GUI
output_pathYesCaminho completo do arquivo de saída .vox

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears the full behavioral burden, yet it says nothing about the fact that this writes/overwrites a .vox file on disk, whether it requires a Goxel runtime, or what side effects export_obj and open_in_gui trigger. Only "Constrói" hints at mutation, leaving reversibility and file-clobbering behavior undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the verb and scope first. The eight-item example list is somewhat redundant with the enum in the schema, but it aids quick recognition and does not bloat the definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter generative/write tool with no annotations and no output schema, the description covers what gets built but not the resulting file location, return value, or whether the model is left open in the GUI. Adequate to call it, thin on consequences.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (object_type, output_path, export_obj, open_in_gui) are already documented in the schema. The description's list of object types merely echoes the enum values with no added syntax or format detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Constrói") plus the resource (a 3D Voxel Art object/weapon/scenery item) and enumerates concrete examples that map onto the object_type enum. It implicitly separates itself from goxel_create_character by scoping to props/weapons/items, but never names the sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical list of object types implies when the tool applies (props, weapons, chests, torches, pillars), but there is no explicit "use this instead of X" or exclusion guidance against goxel_create_character or goxel_run_custom_script. Usage is inferable, not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

goxel_export_modelB

Converte um arquivo de voxels (.vox ou .gox) para .obj, .gltf ou render .png.

NameRequiredDescriptionDefault
input_fileYesArquivo de origem (.vox ou .gox)
output_fileYesArquivo de destino (.obj, .gltf ou .png)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It does not disclose whether an existing output file is overwritten, whether the operation fails without a running Goxel instance, whether .png export means a rendered image rather than a model, or how errors surface — all material for a file-mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is efficient, though its brevity is partly the cause of the missing behavioral detail noted elsewhere rather than a deliberate trade-off.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a file-writing conversion tool with zero annotations and no output schema, the description leaves key gaps: overwrite behavior, runtime prerequisites (headless vs GUI), and what a .png render produces. An agent could call it, but cannot predict side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented with accepted extensions. The description restates the same extension lists and adds nothing further (no path format, no overwrite flag semantics), so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (converts) and resource (voxel file .vox/.gox) plus the exact output formats (.obj, .gltf, .png), so an agent immediately understands the operation. It does not explicitly contrast with the sibling creation/GUI tools, but the export framing makes the distinction obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the tool exists to convert voxel files, and the input/output extensions are stated. There is no guidance on preconditions (must the file already exist? must the Goxel GUI/context be open? absolute vs relative paths?) or on when to prefer this over running a custom script.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

goxel_open_guiC

Abre a janela gráfica do Goxel com um modelo de voxels carregado na tela.

NameRequiredDescriptionDefault
file_pathYesCaminho do arquivo .vox ou .gox para visualizar no Goxel

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of describing behavior. It does not say whether the call blocks until the window closes, what happens if the file is missing or Goxel is not installed, or whether it requires a graphical environment. 'Open the graphical window' hints at a side effect, but it discloses almost no operational behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One efficient sentence with the action front-loaded; nothing is redundant. It could carry one more sentence of behavioral detail without becoming bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a side-effecting GUI-launch tool with no annotations and no output schema, so the description must explain the side effects, whether it blocks, and what the caller gets back. It omits all of this, leaving significant gaps for a tool whose behavior is non-obvious.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% description coverage for the single file_path parameter, already documenting accepted .vox/.gox formats. The description adds no syntax or path-format detail beyond the schema, which is acceptable given the high coverage. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb+resource: it opens the Goxel graphical window and loads a voxel model into it. This is clear enough for an agent to know what happens. However, it never contrasts itself with the sibling tools that create, export, or script models, so the distinction must be inferred from their names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says nothing explicit about when to call this tool instead of a sibling, and it gives no prerequisites. For example, should it be used only for visual inspection after goxel_create_object, and is a display required? The agent must also infer that the tool is a GUI launcher from its name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

goxel_run_custom_scriptB

Executa um script procedural JavaScript arbitrário dentro do motor QuickJS do Goxel para esculturas voxel complexas.

NameRequiredDescriptionDefault
script_codeYesCódigo JavaScript a ser executado dentro do Goxel (acessa goxel.image.activeLayer.volume)
output_vox_pathYesCaminho para salvar o volume final em .vox

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It says 'arbitrary JavaScript' but discloses nothing about sandbox limits, what happens to the existing image/layer, whether the output path is overwritten, error behavior, or execution time/rate concerns — critical gaps for a code-execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. It is efficient, though its brevity leaves behavioral gaps that a longer description should have covered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an arbitrary-code-execution tool with no annotations and no output schema, the description should explain sandbox scope, mutation of the active layer, and overwrite behavior for output_vox_path. None of that is present, so an agent cannot predict side effects or failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds only the QuickJS execution context, nothing about script constraints or expected return/exit semantics beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: executes arbitrary procedural JavaScript inside Goxel's QuickJS engine to build complex voxel sculptures. This differentiates it from the higher-level siblings (create_character, create_object) by implying raw procedural generation, though the contrast is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for complex voxel sculptures' hints that this is the escape hatch when the canned sibling tools are insufficient, but it never names those alternatives or states when not to use it. An agent must infer that this is the fallback path.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedgoxel_create_character
    • First observedgoxel_create_object
    • First observedgoxel_export_model
    • First observedgoxel_open_gui
    • First observedgoxel_run_custom_script
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: character generation, object generation, arbitrary script execution, format conversion, and GUI opening. The character/object split is well-defined by explicit examples (archetypes vs items/props), so misselection risk is low.

Naming Consistency5/5

All tools follow a uniform goxel_verb_noun pattern (create_character, create_object, run_custom_script, export_model, open_gui). No mixed conventions or vague verbs.

Tool Count5/5

Five tools is a well-scoped surface for a voxel art pipeline: generation (two flavors), scripting escape hatch, export, and GUI viewing. Each tool earns its place with no redundancy.

Completeness4/5

Core lifecycle is covered: create (character/object/custom), view (GUI), and export. Minor gaps exist around managing existing assets — no list/inspect, rename, delete, or direct edit of previously created models, though open_gui partially covers loading.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • VoxelForge

    thanakon228
    A
    license
    C
    quality
    F
    maintenance
    A voxel editor with MCP bridge enabling AI agents to create and edit 3D models, supporting .vox/.obj formats, layers, and a web editor.
    27
    MIT

  • clayform

    sezginkipel
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to model, sculpt, rig, animate and bake particle effects by editing a semantic scene document, with built-in software rendering, measurable critics that flag floating or broken geometry, and game-ready glTF export. It exposes templates, atomic edit batches, motion and effect previews, undo history, and no GPU, browser, or Blender required.
    11 npm
    Apache 2.0