minecraft-paper-mcp

Ein MCP-Server zur Verwaltung des Backends eines Paper-Minecraft-Servers – er läuft auf demselben Rechner wie der Minecraft-Server (mit direktem Zugriff auf Dateien und Prozesssteuerung) und ergänzt das um In-Game-Befehle über RCON.

Funktionen

• Prozesssteuerung: server_start, server_stop, server_restart, server_status

• RCON / In-Game-Befehle: rcon_command (beliebiger Befehl), players_list, server_tps, server_say, player_kick, player_ban, player_pardon, player_op, player_deop, whitelist_add, whitelist_remove, give_item, teleport_player, set_gamerule, set_weather, set_time

• Dateien auslesen: whitelist_list, ops_list, banned_players_list, banned_ips_list, server_properties_get, server_properties_set (wirkt erst nach einem Neustart)

• Logs: logs_tail (die letzten N Zeilen ansehen), logs_search (grep mit Regex)

Related MCP server: Minecraft Server MCP

Installation

Voraussetzung ist Node.js 18 oder höher.

cd minecraft-mcp
npm install
npm run build

Paper-Server vorbereiten

1. Aktiviere RCON in der server.properties des Paper-Servers:

   enable-rcon=true
   rcon.port=25575
   rcon.password=ใส่รหัสผ่านที่ตั้งเอง_อย่าใช้ค่าว่าง

2. Wichtig: Falls der RCON-Port von außen erreichbar ist, muss er mit einer Firewall blockiert werden – RCON ist nicht verschlüsselt. Er sollte nur auf 127.0.0.1 lauschen (Standard), wenn der MCP-Server auf demselben Rechner läuft.

3. Starte den Paper-Server einmal neu, damit die RCON-Einstellungen wirksam werden.

Umgebungsvariablen einrichten

Es gibt eine .env.example als Referenz – kopiere sie in .env und trage die tatsächlichen Werte ein (.env ist in .gitignore eingetragen und wird nicht nach GitHub gepusht). Der MCP-Server selbst lädt .env nicht automatisch (er verwendet kein dotenv) – setze die Werte also über env in der claude_desktop_config.json oder exportiere die Variablen vor dem eigentlichen Start. .env dient nur, um die Werte für dich selbst festzuhalten.

In Claude Desktop einrichten

Füge in claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "minecraft-paper": {
      "command": "node",
      "args": ["/absolute/path/to/minecraft-mcp/build/index.js"],
      "env": {
        "MC_SERVER_DIR": "/absolute/path/to/paper-server",
        "MC_START_COMMAND": "java -Xmx6G -Xms2G -jar paper-1.21.jar nogui",
        "MC_RCON_PASSWORD": "รหัสผ่านเดียวกับใน server.properties"
      }
    }
  }
}

Starte Claude Desktop danach neu.

CI

Es gibt einen GitHub-Actions-Workflow (.github/workflows/build.yml), der bei jedem Push und bei pullings gegen main npm install und npm run build auf Node 18.x und 20.x ausführt, um sicherzustellen, dass das Projekt gebaut werden kann. Falls du npm ci statt npm install verwenden möchtest, führe einmal selbst npm install aus, um package-lock.json zu erzeugen, und committe diese Datei danach in das Repo.

Anmerkungen / Hinweise

• server_start/server_restart erzeugen einen abgetrennten (detached) Prozess und speichern die PID in MC_PID_FILE – das funktioniert auch, wenn man den Server als echten Dienst (systemd) betreiben möchte. Der MCP-Server kennt jedoch keine Prozesse, die systemd selbst gestartet hat. Wähle daher eine der beiden Varianten: Entweder startet/stoppt dieser MCP den Server auch, damit er die systemd-Verwaltung nur für die RCON/dateibasierten Tools nutzt.

• server_stop versucht zuerst, den Befehl stop über RCON zu senden (graceful); falls keine RCON-Verbindung möglich ist, wird auf SIGTERM- eine.

• server_properties_set ändert die Datei direkt – einen Server musst du selbst neu starten, damit die Änderung wirksam wird. Ein automatischer Neustart erfolgt nicht.

• Die Befehle ban/kick/whitelist werden über RCON und nicht als direkte Änderung an den JSON-Dateien ausgeführt – das ist sicherer, während der Server läuft.