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.

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

• Was kann Claude damit? (104 Tools)

• „Game from scratch" in einer Pipeline

• Premium-Grafik selbst erzeugen

• Steuerungsstrategie

• Installation

• Claude-Integration

• Sicherheit

• Projektstruktur

• Entwicklung & Tests

Related MCP server: UniMCP4CC

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. Überblick nach Bereich:

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

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/): 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:

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:

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.

Installation

Voraussetzungen

• Windows 10/11

• Unity Hub (Standard: C:\Program Files\Unity Hub\Unity Hub.exe)

• Mindestens ein Unity-Editor über den Hub installiert

• uv (empfohlen) oder Python ≥ 3.10

• Optional für Asset-Tools: Blender, Krita, ein Figma-Account (Token)

Schnellstart

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.

Claude-Integration

Claude Desktop — 1-Klick-Erweiterung (empfohlen)

Fertiges Bundle: 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:

npx -y @anthropic-ai/mcpb@latest pack dist\mcpb dist\unity-hub-mcp.mcpb

Claude Code (CLI/IDE)

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

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 © 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.