MC-Host – Lokaler Minecraft-Hosting-Dienst 🎮

Verwandle deinen Raspberry Pi (oder jeden Linux-Rechner) in einen vollwertigen Minecraft-Hosting-Dienst – wie Aternos, nur bei dir zuhause. Komplett privat, keine Cloud, keine Abos.

---

✨ Features

Feature	Beschreibung
🎮 Alle Server-Typen	Vanilla, Paper, Forge, Fabric, Quilt + Bedrock (BDS)
📦 Alle Versionen	Komplette Versionsliste aus dem Mojang-Manifest (Releases + Snapshots)
⬇️ Auto-Download	Server-JAR/BDS wird automatisch heruntergeladen – kein manuelles Hantieren
🧩 Mod-Store	70.000+ Mods/Plugins von Modrinth – 1-Klick-Installation mit Kompatibilitäts-Check
🪨 Bedrock-Addons	.mcpack/.mcaddon hochladen → automatisch in behavior/resource_packs entpackt
📟 Live-Konsole	Echtzeit-Logs im Browser mit farbcodierten Meldungen
💻 Client-Sync-Tool	mc-sync.py synchronisiert Server-Mods automatisch auf den Spieler-PC
🔌 MCP-Server	Komplette API als MCP-Tools exponiert – jede MCP-GUI kann den Dienst steuern
🌙 Dark Dashboard	Modernes, responsives Web-UI mit Dark Theme (mobil-tauglich)
🔒 100 % Privat	Läuft komplett lokal im Heimnetz – keine Cloud, keine Accounts

---

🚀 Installation

Voraussetzungen

• Python 3.10+ (mit pip und venv)
• Java 17+ (für Minecraft-Java-Server): sudo apt install default-jre-headless
• Git (optional, zum Klonen)

Schnellstart

# 1. Repository klonen
git clone https://github.com/DEIN-USER/mc-host.git
cd mc-host

# 2. Automatisch einrichten (erstellt venv + installiert Abhängigkeiten)
bash install.sh

# 3. Server starten
.venv/bin/python app.py

Oder manuell:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 app.py

Öffne http://<IP>:5000 im Browser (z.B. http://192.168.178.116:5000).

Firewall (optional)

sudo ufw allow from 192.168.178.0/24 to any port 5000 proto tcp
sudo ufw allow from 192.168.178.0/24 to any port 25565 proto tcp

---

📱 Web-Dashboard

Das Dashboard bietet:

• Server-Übersicht – Alle Server als Karten mit Status-LED, Version, Typ und Mod-Anzahl
• Server-Wizard – 4-Schritte-Wizard: Name → Typ → Version → RAM → Erstellen
• Live-Konsole – Echtzeit-Logs mit Farbcodierung (INFO/WARN/ERROR)
• Mod-Store – Modrinth-Suche mit 1-Klick-Installation
• Datei-Upload – .jar/.mcpack/.mcaddon direkt hochladen
• Server-Einstellungen – RAM, Port anpassen
• Landing Page – Marketing-Seite unter /landing.html

---

🔗 API-Referenz

Alle Endpunkte unter http://<host>:5000/api/.

System

Methode	Endpunkt	Beschreibung
GET	/api/status	Health-Check (Service-Status, Server-Anzahl)
GET	/api/versions	Alle verfügbaren Versionen (Vanilla, Paper, Bedrock)

Server-Verwaltung

Methode	Endpunkt	Beschreibung
GET	/api/servers	Alle Server auflisten
POST	/api/servers	Neuen Server erstellen
POST	/api/servers/<name>/start	Server starten
POST	/api/servers/<name>/stop	Server stoppen
POST	/api/servers/<name>/restart	Server neustarten
GET	/api/servers/<name>/logs	Konsolen-Logs abrufen
GET	/api/servers/<name>/settings	Einstellungen abrufen
POST	/api/servers/<name>/settings	Einstellungen ändern
DELETE	/api/servers/<name>	Server löschen (unwiderruflich!)

Mods & Plugins

Methode	Endpunkt	Beschreibung
GET	/api/servers/<name>/mods	Installierte Mods auflisten
POST	/api/servers/<name>/mods	Mod manuell registrieren
POST	/api/servers/<name>/mods/install	Mod aus Modrinth installieren
POST	/api/servers/<name>/mods/upload	Mod-Datei hochladen
GET	/api/servers/<name>/mods/download/<file>	Mod-Datei herunterladen (für Client-Sync)
DELETE	/api/servers/<name>/mods/<file>	Mod entfernen
GET	/api/store/search?q=<query>	Modrinth-Mod-Suche

Beispiele

# Server erstellen
curl -X POST http://localhost:5000/api/servers \
  -H 'Content-Type: application/json' \
  -d '{"name":"survival","version":"1.21.1","type":"vanilla","ram":1024}'

# Mod installieren (Modrinth)
curl -X POST http://localhost:5000/api/servers/survival/mods/install \
  -H 'Content-Type: application/json' \
  -d '{"modId":"AANobbMI","name":"Sodium"}'

# Mod-Datei hochladen
curl -X POST http://localhost:5000/api/servers/survival/mods/upload \
  -F 'file=@sodium-fabric-0.6.jar'

---

💻 Client-Sync-Tool (mc-sync.py)

Das Client-Sync-Tool installiert automatisch alle Server-Mods auf dem Spieler-PC.

Einrichtung (Windows/Linux)

# 1. Python + requests installieren
pip install requests

# 2. Sync starten
py mc-sync.py
# → Beim ersten Start: MC-Host-URL eingeben (z.B. http://192.168.178.116:5000)
# → Wird in ~/.mc-sync.json gespeichert

# Oder direkt:
py mc-sync.py --host http://192.168.178.116:5000 sync DemoWelt

Funktionen

• Server auflisten: py mc-sync.py list
• Mods synchronisieren: py mc-sync.py sync <servername>
• Interaktiver Modus: py mc-sync.py (zeigt Server, fragt nach Auswahl)

Was passiert beim Sync?

Server-Typ	Mod-Ziel auf dem PC
Vanilla/Forge/Fabric	~/.minecraft/mods/
Paper/Spigot	~/.minecraft/plugins/
Bedrock	games/com.mojang/behavior_packs/ + resource_packs/

---

🔌 MCP-Server (mc_host_mcp.py)

MC-Host ist als MCP-Server (Model Context Protocol) exponiert. Jede MCP-fähige GUI oder KI kann den Dienst steuern.

Start

.venv/bin/python mc_host_mcp.py

Test mit MCP Inspector

npx @modelcontextprotocol/inspector -- .venv/bin/python mc_host_mcp.py

Verfügbare MCP-Tools

Tool	Beschreibung
list_servers	Alle Server auflisten
get_status	Service-Status
list_versions	Verfügbare Versionen
create_server	Server erstellen
start_server	Server starten
stop_server	Server stoppen
restart_server	Server neustarten
get_logs	Konsolen-Logs
list_mods	Installierte Mods
search_mods	Modrinth-Suche
install_mod	Mod installieren
remove_mod	Mod entfernen
delete_server	Server löschen

Antigravity / Gemini CLI Konfiguration

{
  "mcpServers": {
    "mc-host": {
      "command": "/home/david/mc-host/.venv/bin/python",
      "args": ["/home/david/mc-host/mc_host_mcp.py"]
    }
  }
}

---

📁 Projektstruktur

mc-host/
├── app.py               # Flask-Backend (REST API + Server-Verwaltung)
├── mc-sync.py            # Client-Sync-Tool (Mods auf Spieler-PC)
├── mc_host_mcp.py        # MCP-Server (API als MCP-Tools)
├── requirements.txt      # Python-Abhängigkeiten
├── install.sh            # Automatisches Setup-Skript
├── static/
│   ├── index.html        # Dashboard SPA (Dark Theme)
│   └── landing.html      # Marketing-Landing-Page
├── servers/              # Server-Daten (pro Server ein Ordner)
│   └── DemoWelt/         # Beispiel: Vanilla 1.20.4
│       ├── server.json   # Server-Konfiguration
│       ├── mods.json     # Installierte Mods
│       ├── server.jar    # Minecraft-Server-JAR
│       ├── console.log   # Konsolen-Ausgabe
│       └── world/        # Welt-Daten
├── PLAN.md               # Feature-Plan
└── README.md             # Diese Datei

---

⚠️ Bekannte Einschränkungen

PaperMC (Cloudflare-Block)

PaperMC blockiert API-Anfragen von bestimmten IPs (Cloudflare-Schutz). Auf dem Raspberry Pi ist die Paper-Versionsliste daher leer und Paper-Server-Downloads schlagen fehl. Workaround: Paper-JAR manuell von papermc.io herunterladen und als server.jar in den Server-Ordner legen.

Forge/Fabric/Quilt (manuelle Installation)

Der automatische Download funktioniert nur für Vanilla und Bedrock. Für Forge, Fabric und Quilt muss die server.jar manuell erstellt werden:

1. Server in MC-Host erstellen (Typ wählen)
2. Installer von der jeweiligen Seite herunterladen:
   • Forge: files.minecraftforge.net
   • Fabric: fabricmc.net
   • Quilt: quiltmc.org
3. Installer ausführen: java -jar forge-installer.jar --installServer
4. Resultierende server.jar in servers/<name>/ legen

Bedrock (BDS) – nur x86_64

Bedrock Dedicated Server (BDS) ist ein x86_64-Binary. Auf dem ARM-basierten Raspberry Pi kann BDS nicht gestartet werden. Setup, Addon-Upload und Konfiguration funktionieren aber problemlos. Start nur auf x86-Rechnern (z.B. Desktop-PC, Intel NUC).

Bedrock-Versionen

Minecraft.net stellt nur die neuesten BDS-Versionen zum Download bereit. Ältere Versionen werden entfernt. MC-Host prüft per HEAD-Request welche Versionen verfügbar sind (Cache: 6h).

Sicherheit

MC-Host ist für den privaten LAN-Betrieb konzipiert. Das Web-UI hat keine Authentifizierung. Nicht im Internet exponieren! Für LAN-Zugriff: Firewall (ufw) auf das lokale Subnetz beschränken.

---

🛠 Entwicklung

# Server im Debug-Modus starten (Auto-Reload)
.venv/bin/python app.py

# MCP-Server testen
npx @modelcontextprotocol/inspector -- .venv/bin/python mc_host_mcp.py

# API testen
curl http://localhost:5000/api/status
curl http://localhost:5000/api/servers

---

📜 Lizenz

MIT – Frei verwendbar, auch kommerziell.