Material Maker MCP

Part of gProdDevKit, Grayson Chalmers' game production / dev kit.

<p align="center"> <img src="docs/images/hero.png" alt="Cobblestone, marble, and raw-crystal materials authored by the server and rendered in 3D" width="100%"> </p>

An MCP server that lets an AI assistant author Material Maker node graphs from natural language, render them headlessly to PBR texture maps, and hand back editable .ptex files you finish in the app.

You describe a material in a sentence. The assistant drafts the node graph, the server validates it against Material Maker's own node catalog and renders it with Godot, and you get back the maps plus an editable graph. The assistant gets you most of the way there; you tweak the rest in Material Maker.

Why this project exists and what it's actually optimizing for is in docs/NORTH_STAR.md.

⚠️ Super, super, super alpha. Read this first.

I am an artist and animator in the game industry, not a software engineer. I do not really know what I am doing on the code side. This project was built mostly by AI assistants with me steering, and it is at an extremely early, rough, experimental stage.

What that means for you:

• Expect breakage. Rough edges, sharp corners, things that only work on the one machine they were built on. It has been verified on exactly one setup (Windows, a specific Godot build, a specific Material Maker checkout).
• No stability promises. Anything can change or break between versions. The unit suite and CI only prove the code behaves on the setup above; nothing here has been exercised by a second person or a second machine.
• Not production-ready. Please do not rely on this for anything that matters. Back up your work. Assume it will misbehave.
• The material "quality" bar is deliberately low. The goal is "gets you 80% of the way there so you finish in the app," not "photoreal." See the Phase-3 scorecard for exactly how well (and badly) it does on 15 prompts: it currently passes all 15 of them by a generous, artist's eyeball standard (the ship gate was 11 of 15).

I am sharing it in the open because it is a fun experiment and someone might find it useful or want to build on it, not because it is polished. Feedback, issues, and "you're doing this wrong" corrections from actual developers are very welcome.

Gallery

Each material below was authored by the server, then its rendered maps were composited onto a sphere, a rounded-bevel cube, and a lathed chess rook on a lit ground plane, so the normal-map relief reads under real lighting instead of as a flat swatch. Full graphs live in the cookbook below (s07_cobblestone, s09_ashlar_wall, s11_marble, gl04_raw_crystal_cluster, sf02_hazard_stripe_panel, f07_herringbone_tweed, t05_cracked_ice, s14_wet_river_stone).

| | | |:--:|:--:| | | | | | | | | | | | |

In motion

The static frame hides how relief plays with light. These sweep the key light across five materials so the normal-map depth reads as it moves.

| | | |:--:|:--:| | | | | | | | | |

Material cookbook

The cookbook is 55 materials across 12 categories (the gallery above is drawn from it), each one a real graph this server authored and then locked after a 3D-preview pass. Every one ships as a tracked .ptex under cookbook/: open cookbook/<category>/<id>.ptex in Material Maker to see the node network, or start from it over MCP with load_example("f07_herringbone_tweed"). The invariants that apply across materials are in docs/AUTHORING.md, also served as the guide://authoring MCP resource; the recipe for each material lives next to its graph as cookbook/<category>/<id>.md. The builders that regenerate the graphs live in quality/.

The full cookbook (55 materials: ceramic, fabrics, glass, leather, metal, organics, painted metal, plastics, sci-fi, stone, terrain, wood)

<p align="center"> <img src="docs/images/cookbook-contact-sheet.png" alt="Contact sheet of all 55 cookbook materials across 12 categories" width="100%"> </p>

Core toolbox

Below the finished cookbook materials sit the single-node building blocks they are made from: two galleries that isolate ONE node at a time so you see its raw, unmixed behavior before it gets composited into anything.

Debug swatches. 19 single-node debug swatches, each wiring exactly one node straight into a Material so what you see IS that node's behavior, no recipe, no blend, nothing to misread. Every swatch also doubles as a live pixel-assertion regression test (tests/test_debug_swatches.py renders it fresh and checks known-answer pixels), so a wiring regression fails a test instead of waiting for a human to notice a material looks wrong. One swatch, slope_blur, ships structure-only: it is a buffer/compute-shader node that cannot render headless, so its tile is black by design, not broken. Legend and known-answers for every swatch are in docs/DEBUG_SWATCHES.md.

<p align="center"> <img src="docs/images/core-toolbox/swatches.png" alt="Contact sheet of the 19 debug swatches, one node isolated per tile" width="100%"> </p>

Noise vocabulary. A gallery of base noise/pattern nodes beyond the two (perlin, voronoi) the cookbook leaned on early: fbm's 8 base functions side by side, plus a cross-family row (anisotropic, truchet, voronoi triangle, wavelet, and more) showing how differently they read. Full writeup, including the "the catalog carries 47 noise nodes, the cookbook effectively used two" problem this was built to fix, is in the Noise vocabulary section of docs/AUTHORING.md.

<p align="center"> <img src="docs/images/noise-gallery/fbm-bases.png" alt="fbm noise node's 8 base functions rendered side by side" width="100%"> </p>

How it works

Material Maker graphs are plain JSON (.ptex), and Material Maker ships a headless CLI export mode. This server sits on top of an existing Material Maker checkout:

1. A catalog builder reads Material Maker's node definitions (addons/material_maker/nodes/*.mmg) into a machine-readable catalog the assistant authors against.
2. The assistant drafts a graph as .ptex JSON. The server validates it against the catalog (returning errors as data so the assistant can self-correct), then renders it by driving Godot's --export-material mode.
3. Rendered maps come back as image files (albedo, normal, roughness/metallic, height), and the .ptex is saved for you to open in Material Maker.

Requirements

• Python 3.10+ (developed and verified on 3.13; older versions declared but not exercised)
• Windows is the only fully verified platform. The render runner falls back to the plain Godot binary on macOS/Linux, but that path is untested.
• Godot 4.7.x (the standard desktop binary; the server prefers the matching _console.exe build on Windows when present, to capture render logs)
• A Material Maker project checkout on disk. The server reads that checkout's node definitions and bundled examples and drives its headless export. Clone it from github.com/RodZill4/material-maker. Material Maker needs a steam_appid.txt (containing 4110830) at the checkout root, or the app self-relaunches and exits on headless render. The upstream repo does not ship this file; create it yourself before your first render (echo 4110830 > steam_appid.txt at the checkout root).

Install

Install from a clone (the supported path for now):

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

Then edit .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 is gitignored and read from the current working directory (or from the path in MM_DOTENV if set). Config can also be supplied via MM_* environment variables, which take precedence over .env. MM_OUTPUT_DIR is optional and defaults to an output/ folder in the working directory.

MM_ALLOWED_ROOTS is optional. When set (an os.pathsep-separated list of directories), the server refuses to read or write paths outside those roots. When unset (the default), paths are unrestricted. Either way, node/example name and basename arguments are always rejected if they contain a path separator or ...

MM_COOKBOOK_DIR is also optional. It points the server at a cookbook of authored graphs (see cookbook/README.md) and defaults to the checkout's own cookbook/ folder, so a git clone needs nothing set. Set it only if you want the server to serve a cookbook from somewhere else.

Either way you get an mm-mcp command on your PATH. (A pip install mm-mcp from PyPI is packaged and ready but not yet published; the clone above is the current route.)

Check your setup

Before wiring it into a client, confirm every prerequisite is in place:

mm-mcp --check

It prints a green/red checklist (Godot binary, Material Maker checkout, node definitions, examples, steam_appid.txt, output dir, and a catalog build) and exits non-zero if anything is missing, so you find problems before your MCP client does. mm-mcp --version prints the version.

Verify

Two smoke scripts prove the render path is alive end to end:

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

On Windows there is also a PowerShell smoke that renders directly through Godot:

pwsh smoke/smoke.ps1

Run the test suite (the one Godot-launching test is marked integration):

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

Connect it to an MCP client

The server speaks MCP over stdio. After installing it is on your PATH as mm-mcp. Point your client at that command with the MM_* variables set.

Claude Desktop / Claude Code (claude_desktop_config.json or an equivalent MCP config) example:

{
  "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_IDLE_EXIT_MINUTES": "120"
      }
    }
  }
}

If mm-mcp is not on the client's PATH, use the venv's Python instead: `"command": "/abs/path/.venv/bin/python"