Material Maker MCP

一个 MCP 服务器，允许 AI 助手根据自然语言编写 Material Maker 节点图，以无头模式将它们渲染为 PBR 纹理贴图，并交回可编辑的 .ptex 文件，让你在应用中完成剩余的工作。

你用一句话描述一种材质。助手起草节点图，服务器根据 Material Maker 自身的节点目录对其进行验证，并用 Godot 渲染；你拿回贴图以及一个可编辑的节点图。助手能帮你完成大部分工作；剩下的你在 Material Maker 中微调。

⚠️ 超级、超级、超级 alpha。先读这里。

我是游戏行业的艺术家和动画师，不是软件工程师。在代码方面我确实不太懂行。这个项目主要是在我的引导下由 AI 助手构建的，目前处于极其早期、粗糙、实验性的阶段。

这对你意味着什么：

• 做好翻车的准备。 粗糙的边缘、尖利的棱角、只在其构建所用的那台机器上才能工作的东西。它只在一套环境上验证过（Windows、特定的 Godot 构建、特定的 Material Maker 检出）。

• 没有稳定性承诺。 任何东西都可能随版本改变或损坏。除了少量冒烟测试和单元测试之外，没有其他测试覆盖。

• 尚不能用于生产。 请不要在任何重要的事情上依赖它。备份你的工作。假定它会出问题。

• 材质的"质量"门槛是故意定低的。 目标是"帮你完成 80% 的工作，剩下的在应用里完成"，而不是"照片级真实"。关于它在 15 个提示词上表现如何（以及多么糟糕），请看 quality/ 记分卡：目前它以宽松的、艺术家目测的标准通过了其中 11 个。

我公开分享它，是因为这是一个有趣的实验，也许有人会觉得有用，或想在此基础上继续构建，而不是因为它已经打磨完善。非常欢迎真正的开发者提供反馈、提交 issue，以及"你做错了"之类的指正。

Related MCP server: Blender MCP

画廊

以下每一张都是由服务器根据旁边的一行提示词生成的，然后以无头模式渲染。完整的节点图和预览见 examples/。

工作原理

Material Maker 节点图是纯 JSON（.ptex），并且 Material Maker 自带无头 CLI 导出模式。这个服务器构建在现有的 Material Maker 检出之上：

1. 目录构建器将 Material Maker 的节点定义（addons/material_maker/nodes/*.mmg）读取为机器可读的目录，供助手据此编写。

2. 助手将节点图起草为 .ptex JSON。服务器根据目录对其进行验证（将错误作为数据返回，以便助手自我修正），然后通过驱动 Godot 的 --export-material 模式进行渲染。

3. 渲染后的贴图以图像文件形式返回（反照率、法线、粗糙度/金属度、高度），.ptex 文件也会被保存，供你在 Material Maker 中打开。

环境要求

• Python 3.13+

• Godot 4.7.x（标准桌面版二进制文件；在 Windows 上，如果存在匹配的 _console.exe 构建，服务器会优先使用它，以便捕获渲染日志）

• 磁盘上的 Material Maker 项目检出。服务器读取该检出的节点定义和内置示例，并驱动其无头导出。从 github.com/RodZill4/material-maker 克隆它。Material Maker 需要在检出根目录有一个 steam_appid.txt（内容为 4110830），否则应用在无头渲染时会自行重启并退出；上游克隆版本已经包含了一个。

安装

git clone https://github.com/graysonchalmers/Tool-MaterialMaker-MCP.git
cd Tool-MaterialMaker-MCP
python -m venv .venv
# Windows:  .\.venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate
pip install -e .

然后将环境模板复制一份，并指向你的机器：

cp .env.example .env

编辑 .env：

MM_GODOT_BINARY=/path/to/Godot_v4.7.x_console.exe
MM_PROJECT_PATH=/path/to/material-maker
MM_OUTPUT_DIR=/path/to/where/rendered/maps/should/go

.env 已被 git 忽略。配置也可以通过 MM_* 环境变量提供，这些变量优先于 .env。

验证

两个冒烟脚本可以证明渲染链路端到端是通的：

# Render a bundled example headlessly and confirm PNGs appear
python smoke/smoke_mcp.py

在 Windows 上还有一个 PowerShell 冒烟脚本，直接通过 Godot 渲染：

pwsh smoke/smoke.ps1

运行测试套件（那个会启动 Godot 的测试标记为 integration）：

pytest -q -m "not integration"   # fast unit + validation tests
pytest -q                        # everything, including a real render

连接到 MCP 客户端

服务器通过 stdio 使用 MCP 协议通信。执行 pip install -e . 之后，它会以 mm-mcp 的形式出现在你的 PATH 中。设置好三个 MM_* 变量，然后让你的客户端指向该命令。

Claude Desktop / Claude Code（claude_desktop_config.json 或等效 MCP 配置）示例：

{
  "mcpServers": {
    "material-maker": {
      "command": "mm-mcp",
      "env": {
        "MM_GODOT_BINARY": "C:\\path\\to\\Godot_v4.7.1-stable_win64_console.exe",
        "MM_PROJECT_PATH": "C:\\path\\to\\material-maker",
        "MM_OUTPUT_DIR": "C:\\path\\to\\output"
      }
    }
  }
}

如果 mm-mcp 不在客户端的 PATH 中，请改用 venv 中的 Python："command": "/abs/path/.venv/bin/python"，"args": ["-m", "mm_mcp.server"]。

配置会在启动时验证，因此缺失或错误的 MM_GODOT_BINARY / MM_PROJECT_PATH 会快速失败并给出可操作的提示信息，而不是在渲染过程中才报错。

工具

服务器提供七个工具和一个资源：

资源 catalog://nodes 提供完整的节点目录。

注意事项与坑

以下是在让无头渲染可靠工作的过程中学到的经验（均在本项目的环境中验证过）：

• 使用 --export-material，而不是 --export。Godot 4 将 --export 保留给了自己的构建导出标志；Material Maker 应用的标志是 --export-material。

• 在 Windows 上使用 _console.exe 二进制文件来捕获 stdout；GUI 版 exe 会返回空日志。

• 不要传递 --headless；纹理渲染需要真实的渲染上下文。

• Material Maker 检出需要 steam_appid.txt（4110830），否则它会自行重启并立即退出。

• normal_map 节点是一个复合节点：它真正的参数是 param0（缓冲大小）、param1（强度）、param2、param4，而不是 amount/size。

项目状态

非常早期的 alpha 版本（见顶部警告）。我自己粗略计划中的阶段 0 到 3 已经完成，并在一台机器上验证过。门禁台账见 STATUS.md，阶段计划见 docs/PLAN.md。生成质量以 quality/ 中一套固定不变的 15 案例测试集来衡量；当前记分卡为 11/15 可用，按艺术家的目测标准（见 quality/scorecards/）。这里的"已验证"意思是"我运行它时它能工作"，而不是"经过实战考验"。

许可证与署名

本项目采用 MIT 许可证（见 LICENSE）。

Material Maker 采用 MIT 许可证，版权所有 (c) Rodolphe Suescun 及贡献者。本项目驱动一个独立的 Material Maker 检出，不会修改或重新分发它。