Unity MCP Claude Code
README.md
# 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? (104 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? (104 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` |
| 18 | **Vision & Verify** *(neu)* | 10 | `dump_scene`, `inspect_gameobject`, `get_ui_layout`, `assert_scene`, `play_and_capture`, `render_scene_multi`, `render_animation_strip`, `run_play_scenario`, `read_image`, `visual_diff` |
---
## Vision & Verify — sehen, verstehen, prüfen
Damit Claude nicht „blind" baut, sondern das Ergebnis wirklich **wahrnimmt und belegt**:
- **Sehen:** `play_and_capture` nimmt echte **Gameplay-Frames im PlayMode** auf (Bewegung/Physik sichtbar, nicht nur ein Standbild); `render_scene_multi` rendert die Szene aus N Winkeln (**Turntable**) oder als **Wireframe** (deckt Lücken/Z-Fighting auf); `render_animation_strip` zeigt einen Clip als **Posen-Serie**; `read_image` gibt Renders als **echtes MCP-Bild** direkt ins Tool-Ergebnis.
- **Verstehen:** `dump_scene` / `inspect_gameobject` lesen die gebaute Szene als **strukturiertes JSON** zurück (Hierarchie, Komponenten, Property-Werte); `get_ui_layout` liest Canvas/RectTransforms — Soll/Ist statt Vermutung.
- **Prüfen:** `assert_scene` wertet Regeln gegen das Dump aus (z. B. „Player hat Rigidbody", „Kamera folgt Player"); `run_play_scenario` misst den **Laufzeit-Zustand** im PlayMode (Bewegung + `[MCP_EVENT]`-Logs); `visual_diff` fängt **visuelle Regressionen** (Baseline-Vergleich + Heatmap).
Der Server ist zudem gegen die offizielle **MCP-Conformance-Suite** geprüft (spec-konform in allem, was er implementiert; alle Tool-Schemas gültig).
---
## „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.*
TDQS
B3.4/5.0
Scored across 94 tools
Disambiguation4/5
Most tools have distinct purposes, and descriptions are detailed. However, with 94 tools, some overlap exists (e.g., multiple download texture tools, multiple install editor tools), which could cause minor confusion. Overall, well differentiated.
Naming Consistency5/5
All tool names follow a consistent verb_noun snake_case pattern (e.g., create_project, build_scene, get_license_status). This makes the API predictable and easy to navigate.
Tool Count2/5
With 94 tools, the set is excessively large. Even for a broad scope like Unity development, this number risks overwhelming agents and increases the chance of misselection. The typical well-scoped range is 3-15 tools.
Completeness5/5
The tool surface is exceptionally comprehensive, covering project management, asset creation, scene building, animation, profiling, testing, external integrations (Blender, Figma, Krita), and more. There are no obvious gaps for the stated purpose of MCP-assisted Unity development.
Maintenance
ActivitySlowing
ResponsivenessNo issues