Unity-MCP-Claude-Code

# Unity MCP Claude Code > **Ein professioneller MCP-Server, mit dem Claude Unity Hub + den Unity-Editor real bedient — und damit komplette Spiele headless baut, eigene Premium-2D/3D-Assets erzeugt und hochwertige PBR-Texturen erstellt.** [](LICENSE)     Dieser Server gibt Claude (Claude Code **und** Claude Desktop) echte Hände in Unity: nicht nur *über* Unity reden, sondern Editoren installieren, Projekte anlegen, Code schreiben, ganze Szenen aus einer Beschreibung bauen, Assets selbst erzeugen, Tests laufen lassen, profilen und am Ende eine fertige `.exe` produzieren — alles automatisiert über die jeweils stabilste Schnittstelle. > Entwickelt und **live verifiziert** gegen **Unity Hub 3.18** + **Unity-Editor 6000.4.10f1 (Unity 6)** auf Windows 11. --- ## Inhalt - [Highlights](#highlights) - [Was kann Claude damit? (94 Tools)](#was-kann-claude-damit-94-tools) - [„Game from scratch" in einer Pipeline](#game-from-scratch-in-einer-pipeline) - [Premium-Grafik selbst erzeugen](#premium-grafik-selbst-erzeugen) - [Steuerungsstrategie](#steuerungsstrategie) - [Installation](#installation) - [Claude-Integration](#claude-integration) - [Sicherheit](#sicherheit) - [Projektstruktur](#projektstruktur) - [Entwicklung & Tests](#entwicklung--tests) --- ## Highlights - 🎮 **Komplette Spiele headless bauen** — von C#-Gameplay über eine aus JSON gebaute Szene bis zur fertigen `.exe`, ohne den Editor manuell anzufassen. - 🧱 **Profi-Szenen aus JSON** — GameObjects, URP-Materialien mit **vollem PBR** (BaseColor + Normal + AO + Metallic/Mask), Physik, beliebige Komponenten-Properties (inkl. Objekt-/Asset-Referenzen), Prefabs, Environment und **Post-Processing** (Bloom/Vignette/Tonemapping …). - 🎨 **Assets selbst erzeugen** — **Blender** headless (Mesh/Material/Bake/Export GLB+FBX, CYCLES-Render), **free-tex-packer** (Sprite-Atlanten), **Figma**-REST (UI → PNG/SVG), **Krita** (.kra → PNG). - 🪨 **Premium-PBR-Texturen** — CC0-Bibliotheken **ambientCG** & **Poly Haven** (gescannt, 1K–8K) plus **prozedurale Blender-Bakes** — automatisch korrekt in URP verdrahtet. - 🤖 **Animation** — Animator-Controller, prozedurale Clips, Clip-Namen aus FBX (z.B. Mixamo/KayKit). - 🔍 **Visuelle QA & Profiling** — Szene → PNG (Claude *sieht* das Ergebnis), Compiler-Fehler strukturiert, Laufzeit-FPS/Speicher/GC. - 🖱️ **GUI-Automation** — echte Klicks/Tastatur + UIA-Inspektion für GUI-only-Flows des Electron-Hubs. - 🛡️ **Sicher by Design** — Confirm-Gates, Pfad-Sandbox, Auto-Backups, redigiertes Audit-Log, Schutz sensibler Hub-Dateien. --- ## Was kann Claude damit? (94 Tools) Vollständiger Katalog mit Parametern: **[docs/TOOLS.md](docs/TOOLS.md)**. Überblick nach Bereich: | # | Bereich | Tools | Beispiele | |---|---|---:|---| | 1 | **Status & Prozesse** | 6 | `get_environment_status`, `launch_hub`, `stop_editor` | | 2 | **Editoren & Installation** | 9 | `install_editor`, `list_installed_editors`, `resolve_editor_changeset` | | 3 | **Projekte** | 8 | `create_project`, `open_project`, `register_project_in_hub` | | 4 | **Editor-Automation** | 9 | `build_player`, `run_tests`, `check_compile`, `run_editor_method` | | 5 | **Pakete (manifest.json)** | 3 | `add_project_package`, `remove_project_package` | | 6 | **Hub-Einstellungen** | 4 | `get_hub_settings`, `set_default_project_dir` | | 7 | **Logs, Jobs & Diagnose** | 8 | `read_editor_log`, `get_job_status`, `detect_errors_in_log` | | 8 | **Lizenz (sicher)** | 3 | `get_license_status`, `create_manual_activation_file` | | 9 | **Deep-Links / GUI-Brücke** | 4 | `open_create_project_ui`, `screenshot_desktop` | | 10 | **Backups & Sicherheit** | 2 | `list_backups`, `restore_backup` | | 11 | **Game-Authoring** | 19 | `write_script`, `build_scene`, `capture_scene_render`, `profile_play`, `build_animator_controller` | | 12 | **GUI-Automation** | 6 | `gui_click`, `gui_inspect_window`, `gui_send_keys` | | 13 | **Asset-Erstellung — Blender** | 4 | `blender_run_python`, `blender_render_preview`, `blender_bake_pbr` | | 14 | **2D-Atlas (free-tex-packer)** | 1 | `pack_sprite_atlas` | | 15 | **Figma-UI-Export** | 2 | `figma_export_images`, `figma_get_outline` | | 16 | **Krita** | 2 | `krita_export`, `krita_open` | | 17 | **Premium-PBR-Texturen** | 4 | `download_pbr_material`, `download_polyhaven_texture` | --- ## „Game from scratch" in einer Pipeline ```text create_project # leeres Unity-Projekt └─ write_script # C#-Gameplay (MonoBehaviours) nach Assets/ └─ build_scene # Welt + Komponenten + Material/Physik aus JSON └─ check_compile # Fehler strukturiert prüfen → ggf. write_script (Auto-Fix) └─ capture_scene_render # Szene → PNG: Claude prüft das Bild └─ build_player # fertige .exe ``` `build_scene` ist das Herzstück: eine **JSON-Spezifikation** beschreibt die ganze Szene und wird über ein injiziertes C#-Editor-Skript in eine echte `.unity` umgesetzt — inklusive URP-/PBR-Materialien, `Rigidbody`/`PhysicsMaterial`, generischem Property-Setter (Field → Property → SerializedObject) mit Objekt-/Asset-Referenzen, Prefabs, Environment/Fog/Ambient und Post-Processing-Volumes. Bewiesen baubar (Demos in [`scripts/`](scripts)): mehrere spielbare 3D-Games headless inkl. Physik, WASD-Steuerung, Score, Bloom-HUD und animierten Charakteren. --- ## Premium-Grafik selbst erzeugen Das **Kohärenz-Prinzip**: eine Quelle = einheitlicher Look. Der Server kann hochwertige Assets **holen**, **selbst erzeugen** *und* korrekt **verbauen**: | Bedarf | Tool(s) | Quelle | |---|---|---| | 3D-Meshes/Materialien | `blender_run_python` | Blender (bpy, headless) → GLB/FBX | | 3D-Vorschau prüfen | `blender_render_preview` | Blender CYCLES → PNG | | **PBR-Texturen (gescannt)** | `search_pbr_materials` / `download_pbr_material` | ambientCG (CC0, 1K–8K) | | **PBR-Texturen (gescannt)** | `search_polyhaven_textures` / `download_polyhaven_texture` | Poly Haven (CC0) | | **PBR-Texturen (prozedural)** | `blender_bake_pbr` | Blender-Bake (brick/rock/wood/metal) | | Sprite-Atlas (2D) | `pack_sprite_atlas` | free-tex-packer | | Game-UI | `figma_export_images` | Figma REST (PNG/SVG) | | 2D-Hand-Polish | `krita_open` / `krita_export` | Krita | Heruntergeladene/gebackene Maps werden in `build_scene` **automatisch korrekt** behandelt: die Normal-Map als `NormalMap` importiert (`_NORMALMAP` + `_BumpMap`/`_BumpScale`), AO/Mask **linear** (`_OcclusionMap` / `_MetallicGlossMap`). Ergebnis: echtes Relief und Tiefe statt flach aufgeklebter Textur — premium Look ohne Handarbeit. > Voraussetzung für die Asset-Tools sind die jeweiligen Programme (Blender, Krita) bzw. ein > `FIGMA_TOKEN`. Fehlt ein Programm, melden die Tools das sauber; der Unity-Kern funktioniert ohne sie. --- ## Steuerungsstrategie Es gibt **keine** allmächtige Unity-API. Stattdessen nutzt der Server einen **Hybrid** aus den jeweils stabilsten Mechanismen — jeder durch direkte Messung bestätigt: | Schicht | Wofür | Stabilität | |---|---|---| | **Unity-Hub-CLI** (`Unity Hub.exe -- --headless …`) | Editoren/Module installieren, auflisten, Install-Pfad | hoch | | **Unity-Editor-CLI** (`Unity.exe -batchmode … -executeMethod`) | Projekt erstellen/öffnen, Build, Tests, Szenenbau | hoch | | **Datei-/JSON-Schicht** | `projects-v1.json`, `user-settings.json`, `manifest.json`, `ProjectVersion.txt` | hoch | | **Log-Schicht** | `Editor.log`, Hub-Logs, NUnit-XML, `[MCP_RESULT]`-Marker | hoch | | **Release-API** | Version → Changeset + Deep-Link | hoch (online) | | **GUI-Automation / Deep-Links / Screenshot** | GUI-only-Flows (Login, Serial-Aktivierung) | best-effort | | **Blender / free-tex-packer / Figma / Krita** | Asset-Erstellung headless | hoch (sofern installiert) | Im Code berücksichtigte Besonderheiten (Auszug): - Unity Hub ist ein **GUI-Subsystem-Electron-Binary** → Ausgabe nur über echte Pipes; harmloses Chromium-/GPU-stderr-Rauschen wird gefiltert. - **Unity-6-Batchmode-Regression**: statt `EditorApplication.Exit()` nur `Environment.ExitCode` + `-quit`, Ergebnis primär aus einer Result-Datei + Watchdog (sonst Zombie-Editor). - Unity-6-Renames werden beachtet (`Rigidbody.drag → linearDamping`, `PhysicMaterial → PhysicsMaterial`, URP-`_BaseColor`/`_Smoothness`, `FindObjectsByType`). - EEVEE rendert headless unter Windows nicht → Blender-Render/-Bake nutzen **CYCLES**. Mehr Detail: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**. --- ## Installation ### Voraussetzungen - Windows 10/11 - [Unity Hub](https://unity.com/download) (Standard: `C:\Program Files\Unity Hub\Unity Hub.exe`) - Mindestens ein Unity-Editor über den Hub installiert - [`uv`](https://docs.astral.sh/uv/) (empfohlen) **oder** Python ≥ 3.10 - *Optional für Asset-Tools:* Blender, Krita, ein Figma-Account (Token) ### Schnellstart ```powershell git clone https://github.com/MauricePutinas/Unity-MCP-Claude-Code.git cd Unity-MCP-Claude-Code uv sync # erstellt .venv + installiert Abhängigkeiten uv run python scripts\test_smoke.py # Funktionstest → "SMOKE TEST OK" ``` Optionale Konfiguration: `config.example.json` → `config.json` kopieren und `allowed_roots` anpassen. Ohne Datei wird alles automatisch erkannt; Schreibzugriffe sind dann auf Default-Projektordner, Hub-AppData und Server-Datenbereich beschränkt. Ausführlich: **[docs/INSTALL.md](docs/INSTALL.md)**. --- ## Claude-Integration ### Claude Desktop — 1-Klick-Erweiterung (empfohlen) Fertiges Bundle: **[`dist/unity-hub-mcp.mcpb`](dist/unity-hub-mcp.mcpb)**. Claude Desktop → **Einstellungen → Erweiterungen → „Erweiterung installieren"** → `.mcpb` auswählen → „Erlaubte Projekt-Ordner" setzen (leer = Auto-Erkennung) → aktivieren. `uv` muss im PATH sein. Bundle neu bauen: ```powershell npx -y @anthropic-ai/mcpb@latest pack dist\mcpb dist\unity-hub-mcp.mcpb ``` ### Claude Code (CLI/IDE) ```powershell claude mcp add --scope user --transport stdio unity-control -- uv --directory "C:\Pfad\zu\Unity-MCP-Claude-Code" run python -m unity_hub_mcp ``` oder projektweit eine `.mcp.json` aus [`claude_code.mcp.example.json`](claude_code.mcp.example.json). Prüfen mit `claude mcp list` bzw. `/mcp` in der Session. ### Claude Desktop (manuell) `%APPDATA%\Claude\claude_desktop_config.json` aus [`claude_desktop_config.example.json`](claude_desktop_config.example.json) befüllen und Claude Desktop **komplett neu starten**. --- ## Sicherheit - **Confirm-Gates:** verändernde/zerstörende Tools verlangen `confirm=true`; ohne Bestätigung gibt es nur eine **Vorschau** (Dry-Run-Charakter). - **Pfad-Sandbox:** Datei-Schreib-/Lösch-Tools wirken nur innerhalb **erlaubter Roots** (`allowed_roots`), Traversal (`..`) wird geblockt. - **Auto-Backups:** vor JSON-/Asset-Änderungen (`list_backups` / `restore_backup`). - **Audit-Log:** jede Aktion wird **redigiert** nach `actions.jsonl` geschrieben — Parameter *und* Ergebnisse laufen durch eine Redaktion (Token/Secrets/License-Entitlements werden ausgeblendet). - **Sensible Hub-Dateien** (`encryptedTokens.json`, `userInfoKey.json`, `Local State`, `Preferences`) werden von den Lese-Pfaden **aktiv verweigert** — nie ausgegeben oder geloggt. - **Keine Secrets** im Code: ein `FIGMA_TOKEN` kommt nur aus der Umgebung/Parametern, nichts wird hartkodiert oder persistiert. > **Ehrliche Hinweise für mächtige Tools:** `run_editor_method` und `blender_run_python` führen > **bewusst beliebigen Code** aus (das ist ihr Zweck). Einige Hub-/Lizenz-/Restore-Schreib-Tools (z.B. > `set_default_project_dir`, `apply_license_file`, `restore_backup`, `import_external_asset`) sind durch > `confirm=true` gesichert, greifen aber außerhalb der `allowed_roots`-Sandbox. Den Server nur in einer > vertrauenswürdigen lokalen Umgebung betreiben. --- ## Projektstruktur ``` unity_hub_mcp/ # der MCP-Server (Tool-Registry in server.py) ├─ core.py # Prozess-Runner, Logging/Redaktion, Backups, Pfad-Sicherheit ├─ settings.py # Pfad-Auflösung (Env → config.json → Auto-Detect) ├─ csharp_templates.py # injiziertes C#-Automationsskript (Szenenbau etc.) ├─ scene_builder.py / authoring.py / editor_cli.py / hub_cli.py / projects.py … ├─ blender.py / texpacker.py / figma.py / krita.py / textures.py # Asset-Erstellung └─ gui.py / process.py / logs.py / releases.py / deeplinks.py scripts/ # Smoke-/Live-Tests + Demo-Pipelines docs/ # TOOLS.md · ARCHITECTURE.md · INSTALL.md dist/ # mcpb/manifest.json + gebautes unity-hub-mcp.mcpb ``` --- ## Entwicklung & Tests ```powershell uv sync uv run python scripts\test_smoke.py # datei-basiert, schnell → "SMOKE TEST OK" uv run python scripts\test_live.py # Hub-CLI + Release-API (read-only) uv run python scripts\demo_make_game.py # baut ein komplettes Mini-Game → .exe ``` Der Server loggt ausschließlich nach **stderr** (stdout ist dem MCP-Protokoll vorbehalten). Eigene Logs und das Audit-Log liegen unter `%LOCALAPPDATA%\unity-hub-mcp\`. --- ## Lizenz [MIT](LICENSE) © 2026 Maurice Putinas *Unity, Unity Hub und das Unity-Logo sind Marken von Unity Technologies. Dieses Projekt ist ein unabhängiges Automationswerkzeug und steht in keiner Verbindung zu Unity Technologies.*