Material Maker MCP

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.

⚠️ 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. There is no test coverage beyond a small smoke and unit set.

• 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 quality/ scorecard for exactly how well (and badly) it does on 15 prompts: it currently passes 11 of them by a generous, artist's eyeball standard.

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.

Related MCP server: Blender MCP

Gallery

Each of these was authored by the server from the one-line prompt beside it, then rendered headlessly. Full graphs and previews are in examples/.

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.13+

• 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 clone already includes one.

Install

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 .

Then copy the environment template and point it at your machine:

cp .env.example .env

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. Config can also be supplied via MM_* environment variables, which take precedence over .env.

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 pip install -e . it is on your PATH as mm-mcp. Point your client at that command with the three 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"
      }
    }
  }
}

If mm-mcp is not on the client's PATH, use the venv's Python instead: "command": "/abs/path/.venv/bin/python", "args": ["-m", "mm_mcp.server"].

Config is validated at startup, so a missing or wrong MM_GODOT_BINARY / MM_PROJECT_PATH fails fast with an actionable message rather than partway through a render.

Tools

The server exposes seven tools and one resource:

Resource catalog://nodes exposes the full node catalog.

Notes and gotchas

Learned while getting headless rendering to work reliably (all verified on this project's setup):

• Use --export-material, not --export. Godot 4 reserved --export for its own build-export flag; the Material Maker app flag is --export-material.

• Use the _console.exe binary on Windows to capture stdout; the GUI exe returns empty logs.

• Do not pass --headless; texture rendering needs a real rendering context.

• The Material Maker checkout needs steam_appid.txt (4110830) or it self-relaunches and exits immediately.

• The normal_map node is a compound node: its real parameters are param0 (buffer size), param1 (strength), param2, param4, not amount/size.

Project status

Very early alpha (see the warning up top). Phases 0 through 3 of my own rough plan are done and verified on one machine. See STATUS.md for the gate ledger and docs/PLAN.md for the phase plan. Authoring quality is measured against a frozen 15-case test set in quality/; the current scorecard is 11/15 usable by an artist's eyeball standard (see quality/scorecards/). "Verified" here means "worked when I ran it," not "battle-tested."

License and attribution

This project is MIT licensed (see LICENSE).

Material Maker is MIT licensed, Copyright (c) Rodolphe Suescun and contributors. This project drives a separate Material Maker checkout and does not modify or redistribute it.