AI导哈

体素模型协议服务器

MagicaVoxel MCP Server是一个用于通过自然语言提示程序化创建、修改和管理.vox体素模型的协议服务器，支持本地机器学习功能。

  • by Mahinika
  • Python
  • 本地部署
  • 30 星标
  • 更新于
在 GitHub 查看 Mahinika/magicavoxel-mcp

使用说明

MagicaVoxel MCP服务器

用于以编程方式与MagicaVoxel.vox文件交互的MCP（模型上下文协议）服务器。这允许您通过自然语言提示创建、修改和管理体素模型。

特性

  • 创建具有自定义尺寸的新体素模型
  • 读取并检查现有的.vox文件
  • 将单个体素放置在特定坐标处
  • 用体素填充矩形区域
  • 列出可用型号
  • 获取详细的模型信息
  • 本地机器学习 -自动质量预测（完全在您的机器上运行！）
  • 智能建议 -基于成功模型的ML参数建议
  • 自动学习 -系统从您的模型中学习并随着时间的推移而改进

安装

  1. 安装Python依赖项：
cd magicavoxel-mcp
pip install -r requirements.txt

备注：ML功能需要 scikit-learn, numpy，以及 joblib 这些内容包含在requirements.txt中。如果你只需要基本功能，ML系统是可选的，并且会优雅地降级。

  1. 在游标设置中配置MCP服务器。

    在光标中，转到设置→ 特性→ 建模上下文协议，并添加新的服务器配置。您可以在以下示例中使用 mcp-config-example.json 作为模板。

    更新配置中的路径以匹配您的系统：

    • args：完整路径 server.py
    • VOX_DIR：通往MagicaVoxel的道路 vox/ 目录
    • EXPORT_DIR：通往MagicaVoxel的道路 export/ 目录

    配置示例：

{
  "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"
      }
    }
  }
}

用法

配置后，您可以使用自然语言提示，如：

基本操作：

  • “创建一个名为“my_model”的新体素模型，尺寸为20x20x20”
  • 将体素放置在my_model中颜色索引为1的坐标（10，10，10）处
  • “在my_model中用颜色索引2填充一个从（0,0,0）到（5,5,5）的框”
  • “列出所有可用的体素模型”
  • “显示castle.vox模型的信息”

形状生成：

  • 在my_model中，在（15,15,15）处创建半径为8的蓝色球体
  • 在my_model中，在（10,0,10）处创建一个半径为5、高度为20的红色圆柱体
  • 在my_model中，在（0,0,0）处创建一个底部为10x10、高度为15的黄色金字塔

模式：

  • 在my_model中创建从（0,0,0）开始、有10个台阶、宽5、深3的楼梯
  • 在my_model中，在（0,0,0）处创建一堵长20、高10的墙

高级：

  • “将my_model中的所有颜色1体素替换为颜色4”
  • 在my_model中将调色板颜色5设置为RGB（255128,0）
  • “计算my_model中每种颜色的体素数量”
  • “复制my_model中从（0,0,0）到（5,5,5）到（10,10,10）的区域”

可用工具

基本操作

  • create_voxel_model -创建具有指定尺寸的新空体素模型
  • read_voxel_model -读取并检查.vox文件结构
  • place_voxel -将单个体素放置在特定坐标处
  • remove_voxel -删除特定坐标处的体素
  • get_voxel -获取特定坐标处体素的颜色索引
  • fill_box -用体素填充矩形区域
  • clear_region -删除矩形区域中的所有体素
  • list_models -列出vox目录中的所有.vox文件
  • get_model_info -获取模型的详细信息（尺寸、体素计数等）
  • delete_model -从vox目录中删除.vox文件
  • copy_model -将.vox文件复制到新文件名

形状生成

  • create_sphere -在指定中心创建具有给定半径的球体（实心或空心）
  • create_cylinder -创建具有指定半径、高度和轴方向的圆柱体
  • create_pyramid -创建底部为矩形（实心或空心）的棱锥体
  • create_torus -创建圆环形状
  • create_cone -创建圆锥体形状

模式生成

  • create_stairs -创建具有指定步数的楼梯
  • create_wall -在X或Z方向上创建墙结构

转换操作

  • copy_region -将体素区域复制到同一模型中的另一个位置
  • move_region -将区域移动到新位置（转换体素）
  • rotate_region -将区域围绕轴旋转90、180或270度
  • mirror_region -在平面上镜像一个区域
  • extrude_region -沿某个方向拉伸区域

颜色和调色板操作

  • replace_color -将一种颜色的所有体素替换为另一种颜色
  • set_palette_color -在模型的调色板中设置特定颜色（RGB值）
  • get_palette -从模型中获取所有调色板颜色
  • count_colors -在模型中按颜色指数计数体素

模型管理

  • merge_models -将两个型号组合成一个，并可选择偏移量

分析工具

  • find_connected_components -查找模型中所有单独的连接部分
  • get_surface_voxels -获取模型中的所有表面（暴露）体素

智能功能（可选）

  • smart_create_model -使用模板支持智能创建体素模型
  • get_suggestions -获取下一步操作的智能建议
  • get_smart_suggestions -基于学习到的模式获取基于机器学习的参数建议
  • list_templates -列出模型创建的可用模板
  • get_operation_stats -获取已执行操作的统计信息
  • analyze_item -使用自动验证和ML质量预测分析模型
  • train_ml_model -从模型历史中训练本地机器学习模型
  • get_proportion_suggestions -获取角色的建议身体部位比例

文件结构

服务器直接使用配置的.vox文件 vox/ 目录。更改会立即保存，并可以在MagicaVoxel中打开。

备注

  • 颜色指数：范围为0-255，对应于MagicaVoxel的调色板。索引0是透明的。
  • 坐标：使用（X，Y，Z）格式，其中：
    • X： 宽度（左右）
    • Y： 高度（垂直、上下）
    • Z： 深度（前后）
  • 型号限制：MagicaVoxel支持高达256×256×256体素的模型
  • 文件格式：服务器实现基本的.vox文件读/写。材质和动画等复杂功能可能需要在MagicaVoxel中手动编辑。

直接函数使用

推荐方法：直接通过Python单行程序使用MCP工具函数，而不是创建独立的脚本。

例子：

# 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)"

为什么？

  • MCP工具旨在通过MCP协议直接使用
  • 直接函数调用更快、更高效
  • 使工作流程与MCP工具使用模式保持一致
  • 不需要中间脚本文件

替代：您还可以通过Cursor的自然语言界面使用MCP工具，该界面将自动调用这些工具。

故障排除

  • 如果模型未出现在MagicaVoxel中，请确保 VOX_DIR 路径正确
  • 确保Python 3.8+已安装并可通过 python 命令
  • 检查MCP服务器是否在游标设置中启用
  • 以编程方式创建的模型将使用默认调色板；您可以在MagicaVoxel中自定义颜色

相关 MCP