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? (94 Tools)
• „Game from scratch" in einer Pipeline
• Premium-Grafik selbst erzeugen
• Steuerungsstrategie
• Installation
• Claude-Integration
• Sicherheit
• Projektstruktur
• 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. Ü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

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:

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.

---

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.