Material Maker MCP

MCP 서버로, AI 어시스턴트가 자연어로 Material Maker 노드 그래프를 작성하고, 이를 헤드리스로 렌더링해 PBR 텍스처 맵으로 만들고, 앱에서 마무리할 수 있는 편집 가능한 .ptex 파일을 돌려주는 서버입니다.

한 문장으로 재질을 설명하면 어시스턴트가 노드 그래프 초안을 작성하고, 서버는 Material Maker 자체 노드 카탈로그에 대해 이를 검증한 뒤 Godot으로 렌더링합니다. 그러면 맵과 편집 가능한 그래프를 돌려받습니다. 어시스턴트가 거의 다 만들어 주므로 나머지는 Material Maker에서 다듬으면 됩니다.

⚠️ 초초초 알파 버전입니다. 먼저 읽어 주세요.

저는 게임 업계에서 아티스트이자 애니메이터로 일하고 있으며, 소프트웨어 엔지니어가 아닙니다. 코드 쪽으로는 제가 뭘 하고 있는지 사실 잘 모릅니다. 이 프로젝트는 제가 방향만 잡고 대부분 AI 어시스턴트가 만든 것이며, 아주 이르고 거칠고 실험적인 단계에 있습니다.

이것이 여러분에게 의미하는 바는 다음과 같습니다.

• 고장을 예상하세요. 거칠고 날카로운 모서리, 만들어진 그 머신에서만 동작하는 것들. 정확히 하나의 환경(Windows, 특정 Godot 빌드, 특정 Material Maker 체크아웃)에서만 검증되었습니다.

• 안정성 보장 없음. 버전 사이에 무엇이든 바거나 깨질 수 있습니다. 작은 스모크 및 유닉 테스트 외에는 테스트 커버리지가 없습니다.

• 프로덕션 준비 완료 아님. 중요한 일에 이걸 의존하지 마세요. 작업을 백업하세요. 제대로 동작하지 않을 거라고 가정하세요.

• 재질 '품질' 기준은 의도적으로 낮습니다. 목표은 '앱에서 마무리할 수 있도록 80%까지 데려다주는 것'이지 '포토리얼'이 아닙니다. 15개 프롬프트에서 얼마나 잘(그리고 나쁘게) 처리하는지 정확히 보려면 quality/ 스코어카드를 참고하세요. 현재는 관대한 아티스트 안목 기준으로 11개를 통과합니다.

이 프로젝트를 공개로 공유하는 이유는 재미있는 실험이고 누군가 유용하게 쓰거나 그 위에 더 만들고 싶어할 수 있기 때문이지, 완성도가 높아서가 아닙니다. 실제 개발자들의 피드백, 이슈, "이렇게 하는 건 틀렸다"는 지적을 매우 환영합니다.

Related MCP server: tdmcp

갤러리

아래 이미지들은 각각 옆의 한 줄 프롬프트로 서버가 작성한 후 헤드리스로 렌더링한 것입니다. 전체 그래프와 미리보기는 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. 렌더링된 맵은 이미지 파일(albedo, normal, roughness/metallic, height)로 반환되며, .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는 gitignore 처리됩니다. 구성은 .env보다 우선하는 MM_* 환경 변수로도 제공할 수 있습니다.

검증

두 개의 스모크 스크립트가 렌더 경로가 엔드 투 엔드로 살아 있음을 증명합니다:

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

Windows에는 Godot을 통해 직접 렌더링하는 PowerShell 스모크도 있습니다:

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 / Clude 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에서는 stdout을 캡처하기 위해 _console.exe 바이너리를 사용하세요. GUI exe는 빈 로그를 반환합니다.

• --headless를 전달하지 마세요. 텍스처 렌더링에는 실제 렌더링 컨텍스트가 필요합니다.

• Material Maker 체크아웃에는 steam_appid.txt(4110830)가 필요합니다. 없으면 앱이 스스로 재실행된 후 즉시 종료됩니다.

• normal_map 노드는 복합 노드입니다. 실제 매개변수는 amount/size가 아니라 param0(버퍼 크기), param1(강도), param2, param4입니다.

프로젝트 상태

매우 이른 알파 버전입니다(위의 경고 참조). 제 대략적인 계획의 0~3단계가 완료되었고 한 대의 머신에서 검증되었습니다. 게이트 대장은 STATUS.md를, 단계별 계획은 docs/PLAN.md를 참조하세요. 저작 품질은 quality/에 고정된 15개 테스트 세트로 측정됩니다. 현재 스코어카드는 아티스트의 안목 기준으로 11/15가 사용 가능합니다(quality/scorecards/ 참조). 여기서 '검증됨'은 '제가 실행했을 때 작동했다'는 뜻이지 '실전 검증을 거쳤다'는 뜻이 아닙니다.

라이선스 및 저작자 표시

이 프로젝트는 MIT 라이선스입니다(LICENSE 참조).

Material Maker는 MIT 라이선스이며, Copyright (c) Rodolphe Suescun and contributors입니다. 이 프젝트는 별도의 Material Maker 체크아웃을 구동하며 이를 수정하거나 재배포하지 않습니다.