Material Maker MCP

MCPサーバーで、AIアシスタントが自然言語からMaterial Makerのノードグラフを作成し、ヘッドレスでPBRテクスチャマップにレンダリングし、アプリ内で仕上げるための編集可能な.ptexファイルを返すことができます。

素材を一文で説明すると、アシスタントがノードグラフを草案し、サーバーがMaterial Maker自身のノードカタログに対して検証してGodotでレンダリングし、マップと編集可能なグラフが返ってきます。アシスタントが大部分を進めてくれるので、残りはMaterial Makerで調整します。

⚠️ 超・超・超アルファ版。最初に読んでください。

私はゲーム業界のアーティスト兼アニメーターであり、ソフトウェアエンジニアではありません。コード面では本当に分かっていないことが多いです。このプロジェクトは、私が舵取りをしながら主にAIアシスタントによって構築されたもので、極めて初期の粗い実験段階にあります。

それがあなたにとって意味すること：

• 壊れることを想定してください。 粗い部分、鋭い角、構築された1台のマシンでしか動かないものがあります。正確に1つの環境（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. レンダリングされたマップが画像ファイル（アルベド、ノーマル、ラフネス/メタリック、ハイト）として返され、.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されています。設定はMM_*環境変数を介して提供することもでき、これらは.envより優先されます。

動作確認

2つのスモークスクリプトで、レンダーパスがエンドツーエンドで機能していることを確認します：

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

Windowsでは、Godotを直接通してレンダリングするPowerShellスモークもあります：

pwsh smoke/smoke.ps1

テストスイートを実行します（Godotを起動する1つのテストは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に追加されます。3つの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が欠落または誤っている場合は、レンダリングの途中ではなく、対処可能なメッセージとともにすぐに失敗します。

ツール

サーバーは7つのツールと1つのリソースを公開しています：

リソースcatalog://nodesは完全なノードカタログを公開します。

注意点と落とし穴

ヘッドレスレンダリングを確実に動作させるまでに学んだこと（すべてこのプロジェクトの環境で検証済み）：

• --exportではなく--export-materialを使用します。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までが完了し、1台のマシンで検証されています。ゲート台帳はSTATUS.md、フェーズ計画はdocs/PLAN.mdを参照してください。作成品質はquality/の固定された15ケースのテストセットで測定されています。現在のスコアカードは、アーティストの目視基準で11/15が使用可能です（quality/scorecards/を参照）。ここでの「検証済み」は「実行したときに動作した」という意味であり、「実戦で鍛えられた」という意味ではありません。

ライセンスと帰属

このプロジェクトはMITライセンスです（LICENSEを参照）。

Material MakerはMITライセンスであり、Copyrigh(t c) Rodolphe Suescun and contributorすです。このプロジェクトは別のMaterial Makerチェックアウトを駆動するものであり、それを変更したり再配布したりしません。