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

Related MCP server: Minecraft MCP Server

🚀 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

Server-Verwaltung

Mods & Plugins

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?

🔌 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

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.