Goxel-MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GOXEL_APP | No | Official Goxel app (used with `live: false`). | /Applications/goxel.app |
| GOXEL_REF | No | Used by `scripts/build-goxel.sh`: the Goxel revision to build. | |
| GOXEL_SRC | No | Used by `scripts/build-goxel.sh`: path to existing Goxel sources instead of cloning them into `goxel-src/`. | |
| GOXEL_REPO | No | Used by `scripts/build-goxel.sh`: the Goxel repository to clone. | |
| GOXEL_MCP_SOCKET | No | Path of the bridge socket. Goxel opens the socket only when it is started with `--mcp-socket` or this environment variable. | |
| GOXEL_MCP_GOXEL_BIN | No | Goxel build with the bridge. | goxel-build/goxel |
| GOXEL_MCP_LOG_LEVEL | No | Log level: `debug`, `info`, `warn` or `error`. Logs go to stderr; stdout is only used by the MCP protocol. | info |
| GOXEL_MCP_WORKSPACE | No | The workspace is the only folder the server reads and writes. Your models, exports and previews go there, and the server keeps its backups and the bridge socket in `<workspace>/.goxel-mcp/`. When the variable is not set, the current directory is used. | current directory |
| GOXEL_MCP_SKIP_GOXEL | No | Set to `1` to skip the tests that use the Goxel build (validation, glTF export, live editing). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| goxel_infoA | Server version, Goxel versions (sources, app, bridge binary), mode (file / live), supported formats and a summary of the current scene. |
| goxel_new_sceneA | Create an empty voxel scene. If the current scene has unsaved changes, an autosave is written to .goxel-mcp/backups/ first. |
| goxel_open_sceneB | Open an existing voxel file (.gox, .vox, .txt) from the workspace. In live mode the file is opened in the Goxel editor. |
| goxel_add_voxelsA | Add (or replace) many individual voxels in a single operation. Best for geometry computed by a script. For shapes use goxel_draw_primitive. |
| goxel_draw_primitiveA | Apply a list of up to 500 shape operations: box, sphere (or ellipsoid), cylinder (inner_radius for tires and tubes), cone, line (with a thickness) and points. Each operation has a mode: add (create / overwrite), remove (erase) or paint (recolor existing voxels only), an optional layer (created if missing), clip planes (for slopes and bevels) and mirror copies. Operations are applied in order; everything is validated before the scene is modified. |
| goxel_erase_regionA | Remove the voxels in a region (min/max box and/or shape), optionally only the ones of a given color. Can be undone with goxel_undo. |
| goxel_recolor_regionA | Change the color of existing voxels in a region and/or of a given color (for example: gray rims -> black). |
| goxel_transformB | Translate the voxels of a layer (or of a region of it) by an integer offset. |
| goxel_layersB | Manage layers: list, create, delete, rename, set_visible, set_active, duplicate, clear, merge_into (copy the voxels of the layer into 'target' and delete it). |
| goxel_get_voxelsA | Scene summary (layers, bounding boxes, most used colors) and, optionally, the list of voxels of a region. |
| goxel_render_previewB | Render a PNG image of the scene to check the model visually, and optionally save it. The internal renderer is orthographic and needs no OpenGL; engine='goxel' asks the running Goxel editor (live mode) to render its current view. |
| goxel_save_sceneA | Save the scene in Goxel's native format (.gox). Without 'path', the current file of the scene is used. Existing files are not replaced without overwrite=true (except the scene's own file); the previous version is always copied to .goxel-mcp/backups/. In live mode Goxel itself writes the file. |
| goxel_exportA | Export the scene. Native formats: gox, vox, obj, txt, png (obj + mtl is the simplest choice for Blender; vox for MagicaVoxel). With Goxel's own exporters (needs the Goxel build with the bridge): gltf, glb, ply, qubicle, kv6, kvx, vxl, povray (gltf / glb also open in Blender). The format is deduced from the file extension when omitted. |
| goxel_validate_sceneA | Check the integrity of a .gox / .vox / .txt file (structure, voxels, colors). When the Goxel build is available, the file is also loaded with Goxel's own parser and compared voxel by voxel. Without 'path', the scene in memory is validated (through a temporary copy). |
| goxel_open_in_appA | Open the scene in the Goxel editor. live=true (the default when the Goxel build with the bridge is available) starts Goxel with the bridge and switches to live editing: the following tool calls modify the scene open in the editor. live=false tries to open the file in the official Goxel app (no control; that app may need File > Open). |
| goxel_liveA | Status of the connection to a running Goxel: status, connect (to a Goxel already started with the bridge), disconnect (back to file mode, keeping the current scene in memory). |
| goxel_undoB | Undo (or redo) the last operations. In live mode Goxel's own history is used. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 17 tools
Most tools target clear, distinct operations, and the descriptions actively disambiguate the risky pairs (add_voxels vs draw_primitive, save_scene vs export, erase_region vs draw_primitive remove mode). The main residual overlaps are goxel_open_scene vs goxel_open_in_app and the recolor/erase vs draw_primitive paint/remove modes, which an agent could still mix up.
All names are snake_case with a uniform goxel_ prefix and mostly follow verb_noun (draw_primitive, save_scene, erase_region). A few are noun-only namespace multiplexers (goxel_layers, goxel_live, goxel_info, goxel_undo), which is a minor deviation but still readable and predictable.
17 tools is slightly above the comfortable range but each covers a real facet of voxel editing (scene lifecycle, geometry, layers, render, export, live bridge). A couple of entries (open_scene vs open_in_app, save_scene vs export) could be consolidated, but nothing is obviously filler.
The surface covers the full lifecycle: create/open, edit (add, draw, erase, recolor), inspect, layers, undo/redo, preview, validate, save and export across many formats. Remaining gaps are notable but workaroundable: goxel_transform only translates (no rotate/scale/mirror as a standalone op), and there is no explicit palette or region copy/paste management.