Minecraft Ops MCP

Ein MCP-stdio-Dienst für die Verwaltung und den Betrieb von Minecraft-Servern. Die aktuelle Version basiert auf dem offiziellen MCP Python SDK und unterstützt folgende Backends:

• MCSManager API: Instanz-Lebenszyklus, Protokolle, Dateiverwaltung, Konsolenbefehle.

• RCON: Fallback für traditionelle Konsolenbefehle.

• Minecraft Server Management Protocol (MSMP): JSON-RPC over WebSocket-Verwaltungsprotokoll für Minecraft Java 1.21.9+.

Dokumentation

• Benutzerhandbuch: docs/USER_MANUAL.md

• Entwickler-Framework-Anleitung: docs/DEVELOPER_GUIDE.md

• Aktuelle Einschränkungen und Roadmap: docs/LIMITATIONS.md

• Integrationstestbericht: docs/TEST_REPORT_2026-04-14.md

• Release-Checkliste: docs/RELEASE_CHECKLIST.md

• Sicherheitshinweise: SECURITY.md

• Änderungsprotokoll: CHANGELOG.md

Ausführung

Es wird empfohlen, die Projektabhängigkeiten in der aktuellen Python-Umgebung zu installieren und dann auszuführen:

cd /home/damoc/codes/minecraft-ops-mcp
python3 -m pip install -e .
minecraft-ops-mcp

Für die Entwicklung und das Debugging kann auch explizit PYTHONPATH angegeben werden:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -m minecraft_ops_mcp

Entwicklung und Tests

Unit-Tests:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -B -m unittest discover -s tests

Syntaxprüfung:

python3 -m compileall -q src scripts

Protokoll-Ebene Integrationstests finden Sie unter docs/TEST_REPORT_2026-04-14.md und docs/RELEASE_CHECKLIST.md.

Beispiel für MCP-Client-Konfiguration

{
  "mcpServers": {
    "minecraft-ops": {
      "command": "python3",
      "args": ["-m", "minecraft_ops_mcp"],
      "cwd": "/home/damoc/codes/minecraft-ops-mcp",
      "env": {
        "PYTHONPATH": "src",
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "replace-me",
        "MCSM_DEFAULT_DAEMON_ID": "replace-me",
        "MCSM_DEFAULT_INSTANCE_UUID": "replace-me",
        "RCON_HOST": "127.0.0.1",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "replace-me",
        "MSMP_URL": "ws://127.0.0.1:25585",
        "MSMP_SECRET": "replace-me",
        "MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST": "list,time,help",
        "MINECRAFT_OPS_RAW_COMMAND_DENYLIST": "stop,op,deop,ban,ban-ip"
      }
    }
  }
}

Sie können sich auch auf .env.example beziehen und die Variablen in Ihre MCP-Client-Konfiguration einfügen. Der Dienst selbst liest die .env-Datei nicht automatisch, um zu vermeiden, dass die Herkunft der Laufzeitkonfiguration implizit wird.

Hauptwerkzeuge

MCSManager:

• server.list_daemons

• server.get_daemon_system

• server.list_instances

• server.get_instance

• server.start

• server.stop

• server.restart

• server.kill

• server.send_command

• server.get_logs

• instance.create

• instance.update_config

• instance.update_config_patch

• instance.clone_from_template

• instance.delete

• instance.reinstall

• instance.run_update_task

• file.list

• file.read

• file.download_prepare

• file.download_local

• file.upload_prepare

• file.upload_local

• file.upload_url

• file.write

• file.write_new

• file.delete

• file.move

• file.copy

• file.mkdir

• file.touch

• file.compress

• file.uncompress

Backend-übergreifende Hilfsprogramme:

• server.save_world: Priorität MSMP, dann RCON, dann MCSManager.

• server.broadcast: Priorität MSMP, dann RCON, dann MCSManager.

RCON:

• rcon.command

• rcon.list_players

• rcon.time_query

• rcon.save_all

MSMP:

• msmp.discover

• msmp.call

• msmp.players.list

• msmp.players.kick

• msmp.server.status

• msmp.server.save

• msmp.server.stop

• msmp.bans.get

• msmp.bans.add

• msmp.bans.remove

• msmp.bans.set

• msmp.bans.clear

• msmp.ip_bans.get

• msmp.ip_bans.add

• msmp.ip_bans.remove

• msmp.ip_bans.set

• msmp.ip_bans.clear

• msmp.allowlist.get

• msmp.allowlist.add

• msmp.allowlist.remove

• msmp.allowlist.set

• msmp.allowlist.clear

• msmp.operators.get

• msmp.operators.add

• msmp.operators.remove

• msmp.operators.set

• msmp.operators.clear

• msmp.gamerules.get

• msmp.gamerules.update

• msmp.server_settings.get

• msmp.server_settings.list

• msmp.server_settings.set

Sicherheitsrichtlinien

Operationen mit hohem Risiko erfordern explizite Parameter:

{ "confirm": true }

Wenn Sie nur möchten, dass der Agent zuerst erklärt, was er tun wird, übergeben Sie:

{ "dry_run": true }

Zu den risikoreichen Tools gehören das Starten/Stoppen/Neustarten/Beenden von Instanzen, Rohbefehle, Dateischreiben/-löschen/-verschieben/-komprimieren/-dekomprimieren/-hochladen, Herunterladen auf den MCP-Host, Kicken, Verbannen, Änderungen an Whitelist/OP/Spielregeln/Servereinstellungen usw. Alle Tool-Aufrufe werden in einem Audit-Protokoll protokolliert, Standardspeicherort:

/tmp/minecraft-ops-mcp-audit.jsonl

Dies kann durch Setzen von MINECRAFT_OPS_AUDIT_LOG= auf einen leeren Wert deaktiviert werden.

Rohbefehle können zusätzlich durch eine Allowlist/Denylist auf Präfix-Ebene weiter eingeschränkt werden:

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip

Backend-Empfehlungen

• Instanz-Lebenszyklus, Protokolle und Dateiverwaltung: Bevorzugen Sie die MCSManager API.

• Spieler, Whitelist, OP, Spielregeln, Servereinstellungen: Bevorzugen Sie MSMP.

• Ältere Serverversionen oder Funktionen, die von MSMP nicht abgedeckt werden: Verwenden Sie RCON oder MCSManager-Rohbefehle als Fallback.

Setzen Sie RCON, MSMP oder MCSManager API-Keys nicht dem öffentlichen Internet aus. MSMP/RCON sollten idealerweise nur auf localhost, VPN oder Tunneln lauschen; für MCSManager werden API-Keys mit niedrigen Berechtigungen empfohlen.

MSMP-Parameterbeschreibung

msmp.call übergibt JSON-RPC params unverändert, was für neue Methoden mit großen Server-/Versionsunterschieden geeignet ist:

{
  "method": "minecraft:server/status",
  "read_only": true
}

Für Schreibvorgänge verwenden Sie bitte confirm=true oder führen Sie zuerst dry_run=true aus. read_only=true überspringt die Bestätigung nur für schreibgeschützte MSMP-Methoden in der Whitelist, wie z. B. rpc.discover, minecraft:players, minecraft:server/status, Listenabfragen und das Lesen von Servereinstellungen.