MagicaVoxel MCP Server

An MCP (Model Context Protocol) server for interacting with MagicaVoxel .vox files programmatically. This allows you to create, modify, and manage voxel models through natural language prompts.

Features

• Create new voxel models with custom dimensions
• Read and inspect existing .vox files
• Place individual voxels at specific coordinates
• Fill rectangular regions with voxels
• List available models
• Get detailed model information
• Local Machine Learning - Automatic quality prediction (runs entirely on your machine!)
• Intelligent Suggestions - ML-powered parameter suggestions based on your successful models
• Auto-Learning - System learns from your models and improves over time

Installation

1. Install Python dependencies:

cd magicavoxel-mcp
pip install -r requirements.txt

Note: The ML features require scikit-learn, numpy, and joblib which are included in requirements.txt. If you only need basic features, the ML system is optional and will gracefully degrade.

2. Configure the MCP server in your Cursor settings.

   In Cursor, go to Settings → Features → Model Context Protocol, and add a new server configuration. You can use the example in mcp-config-example.json as a template.

   Update the paths in the configuration to match your system:

   • args: Full path to server.py
   • VOX_DIR: Path to your MagicaVoxel vox/ directory
   • EXPORT_DIR: Path to your MagicaVoxel export/ directory

   Example configuration:

{
  "mcpServers": {
    "magicavoxel": {
      "command": "python",
      "args": [
        "C:/Users/Ropbe/Desktop/MagicaVoxel-0.99.7.2-win64/magicavoxel-mcp/server.py"
      ],
      "env": {
        "VOX_DIR": "C:/Users/Ropbe/Desktop/MagicaVoxel-0.99.7.2-win64/vox",
        "EXPORT_DIR": "C:/Users/Ropbe/Desktop/MagicaVoxel-0.99.7.2-win64/export"
      }
    }
  }
}

Usage

Once configured, you can use natural language prompts like:

Basic Operations:

• "Create a new voxel model called 'my_model' with dimensions 20x20x20"
• "Place a voxel at coordinates (10, 10, 10) with color index 1 in my_model"
• "Fill a box from (0,0,0) to (5,5,5) with color index 2 in my_model"
• "List all available voxel models"
• "Show me information about the castle.vox model"

Shape Generation:

• "Create a blue sphere at (15, 15, 15) with radius 8 in my_model"
• "Create a red cylinder at (10, 0, 10) with radius 5 and height 20 in my_model"
• "Create a yellow pyramid at (0, 0, 0) with base 10x10 and height 15 in my_model"

Patterns:

• "Create stairs starting at (0, 0, 0) with 10 steps, width 5, depth 3 in my_model"
• "Create a wall at (0, 0, 0) with length 20, height 10 in my_model"

Advanced:

• "Replace all color 1 voxels with color 4 in my_model"
• "Set palette color 5 to RGB(255, 128, 0) in my_model"
• "Count how many voxels of each color are in my_model"
• "Copy the region from (0,0,0) to (5,5,5) to (10,10,10) in my_model"

Tools Available

Basic Operations

• create_voxel_model - Create a new empty voxel model with specified dimensions
• read_voxel_model - Read and inspect a .vox file structure
• place_voxel - Place a single voxel at specific coordinates
• remove_voxel - Remove a voxel at specific coordinates
• get_voxel - Get the color index of a voxel at specific coordinates
• fill_box - Fill a rectangular region with voxels
• clear_region - Remove all voxels in a rectangular region
• list_models - List all .vox files in the vox directory
• get_model_info - Get detailed information about a model (dimensions, voxel count, etc.)
• delete_model - Delete a .vox file from the vox directory
• copy_model - Copy a .vox file to a new filename

Shape Generation

• create_sphere - Create a sphere at specified center with given radius (solid or hollow)
• create_cylinder - Create a cylinder with specified radius, height, and axis direction
• create_pyramid - Create a pyramid with rectangular base (solid or hollow)
• create_torus - Create a torus (donut) shape
• create_cone - Create a cone shape

Pattern Generation

• create_stairs - Create a staircase with specified number of steps
• create_wall - Create a wall structure in X or Z direction

Transform Operations

• copy_region - Copy a region of voxels to another location in the same model
• move_region - Move a region to a new location (translates voxels)
• rotate_region - Rotate a region 90, 180, or 270 degrees around an axis
• mirror_region - Mirror a region across a plane
• extrude_region - Extrude a region in a direction

Color & Palette Operations

• replace_color - Replace all voxels of one color with another color
• set_palette_color - Set a specific color in the model's palette (RGB values)
• get_palette - Get all palette colors from a model
• count_colors - Count voxels by color index in a model

Model Management

• merge_models - Combine two models into one with optional offset

Analysis Tools

• find_connected_components - Find all separate connected pieces in a model
• get_surface_voxels - Get all surface (exposed) voxels in a model

Intelligence Features (Optional)

• smart_create_model - Intelligently create a voxel model with template support
• get_suggestions - Get intelligent suggestions for next operations
• get_smart_suggestions - Get ML-powered parameter suggestions based on learned patterns
• list_templates - List available templates for model creation
• get_operation_stats - Get statistics about operations performed
• analyze_item - Analyze models with automatic validation and ML quality prediction
• train_ml_model - Train local machine learning models from your model history
• get_proportion_suggestions - Get suggested body part proportions for characters

File Structure

The server works directly with .vox files in the configured vox/ directory. Changes are saved immediately and can be opened in MagicaVoxel.

Notes

• Color indices: Range from 0-255 and correspond to MagicaVoxel's palette. Index 0 is transparent.
• Coordinates: Use (X, Y, Z) format where:
  • X: Width (left-right)
  • Y: Height (vertical, up-down)
  • Z: Depth (front-back)
• Model limits: MagicaVoxel supports models up to 256×256×256 voxels
• File format: The server implements basic .vox file reading/writing. Complex features like materials and animations may require manual editing in MagicaVoxel.

Direct Function Usage

Recommended Approach: Use MCP tool functions directly via Python one-liners rather than creating standalone scripts.

Example:

# Direct function usage (recommended)
python -c "import sys; sys.path.insert(0, 'magicavoxel-mcp'); from vox_utils import VoxelModel, write_vox_file; from pathlib import Path; model = VoxelModel(10,10,10); model.fill_box(0,0,0,5,5,5,1); write_vox_file(Path('vox/model.vox'), model)"

Why:

• MCP tools are designed to be used directly through the MCP protocol
• Direct function calls are faster and more efficient
• Keeps workflow consistent with MCP tool usage patterns
• No need for intermediate script files

Alternative: You can also use the MCP tools through Cursor's natural language interface, which will call the tools automatically.

Troubleshooting

• If models don't appear in MagicaVoxel, make sure the VOX_DIR path is correct
• Ensure Python 3.8+ is installed and accessible via the python command
• Check that the MCP server is enabled in Cursor settings
• Models created programmatically will use a default palette; you can customize colors in MagicaVoxel