Entwickler/MCP-Server

Hostwolf-MCP-Server

Mit @hostwolf/mcp verwalten KI-Assistenten deine Hostwolf-Gameserver. Es funktioniert mit Claude, Cursor, VS Code und jedem anderen Client, der das Model Context Protocol unterstützt. Frag zum Beispiel:

• „Warum ist mein Minecraft-Server letzte Nacht abgestürzt?“
• „Installiere EssentialsX und starte neu.“
• „Sichere Valheim und stell es dann auf den öffentlichen Testzweig um.“
• „Banne den Spieler griefer123 und sag allen, warum.“
• „Starte jeden Tag um 4 Uhr alle Server neu.“

Einrichtung#

1. Erstelle einen API-Schlüssel unter panel.hostwolf.net/account/api.
2. Verbinde deinen Client. Du kannst den gehosteten Server unter https://hostwolf.net/mcp nutzen (nichts zu installieren) oder ihn aus dem Download selbst betreiben (benötigt Node.js 18+).

Gehostet: https://hostwolf.net/mcp#

Nichts zu installieren und immer die neueste Version. Dein Client sendet deinen Schlüssel mit jeder Anfrage; wir speichern ihn nie.

claude mcp add --transport http hostwolf https://hostwolf.net/mcp --header "Authorization: Bearer ptlc_your_key"

{
  "mcpServers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hostwolf.net/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer ptlc_your_key" }
    }
  }
}

{
  "mcpServers": {
    "hostwolf": {
      "url": "https://hostwolf.net/mcp",
      "headers": { "Authorization": "Bearer ptlc_your_key" }
    }
  }
}

{
  "servers": {
    "hostwolf": {
      "type": "http",
      "url": "https://hostwolf.net/mcp",
      "headers": { "Authorization": "Bearer ptlc_your_key" }
    }
  }
}

Optionen kommen an die URL: https://hostwolf.net/mcp?readonly=1 bietet nur lesende Werkzeuge, und ?servers=1a2b3c4d,5e6f7a8b beschränkt den Assistenten auf diese Server. Ist dein Schlüssel auf bestimmte IP-Adressen beschränkt, erlaube zusätzlich 162.55.180.229, die Adresse des gehosteten Servers.

Selbst betreiben#

Derselbe Server als Download. Er läuft auf deinem Computer, dein Schlüssel verlässt ihn also nie.

claude mcp add hostwolf -e HOSTWOLF_API_KEY=ptlc_your_key -- npx -y https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz

{
  "mcpServers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz"],
      "env": { "HOSTWOLF_API_KEY": "ptlc_your_key" }
    }
  }
}

{
  "mcpServers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz"],
      "env": { "HOSTWOLF_API_KEY": "ptlc_your_key" }
    }
  }
}

{
  "servers": {
    "hostwolf": {
      "command": "npx",
      "args": ["-y", "https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz"],
      "env": { "HOSTWOLF_API_KEY": "ptlc_your_key" }
    }
  }
}

Einstellungen#

Für den selbst betriebenen Server; der gehostete nimmt stattdessen ?readonly=1 und ?servers= an seiner URL.

Werkzeuge#

Du kannst Server über ihre ID oder ihren Namen ansprechen („mein Survival-Server“). Jedes Werkzeug ruft die REST-API über das SDK auf, alles, was ein Werkzeug noch nicht kann, ist also nur ein paar Zeilen Code entfernt.

Ansehen und diagnostizieren:

• list_servers: Status, Adresse und RAM-Nutzung.
• get_server: Details zu einem Server.
• get_console: letzte Konsolenzeilen.
• diagnose_server: führt die „Fix my server“-Prüfungen aus.
• list_players.

Steuerung:

• power_server: starten, stoppen, neu starten oder beenden (kill).
• send_command.
• player_action: kicken, bannen, entbannen oder Rundnachricht.
• reinstall_server.

Dateien:

• list_files.
• read_file: blättert durch lange Dateien.
• write_file.
• rename_file.
• delete_files.

Backups:

• list_backups.
• create_backup.
• restore_backup.
• delete_backup.

Konfiguration:

• get_startup und set_startup_variable.
• get_game_settings und update_game_settings.
• get_game_versions und set_game_version.

Mods:

• search_addons.
• list_installed_addons.
• install_addon und uninstall_addon.
• search_modpacks und install_modpack.

Datenbanken:

• list_databases: Verbindungsdaten und wer sich von außen verbinden darf.
• create_database: die erste Datenbank auf einem Server wartet etwa 40 Sekunden, während der Datenbankdienst startet.
• set_database_remote_access: die IPs anderer Server erlauben oder jeden mit dem Passwort.
• rotate_database_password und delete_database.
• export_database und import_database: eine .sql.gz auf deinem Computer speichern oder eine laden. Nur beim selbst betriebenen Server.

Passwörter bleiben verborgen, außer du bittest deinen Assistenten, sie anzuzeigen.

Zeitpläne:

• list_schedules.
• create_schedule.
• delete_schedule.

Konto:

• get_plans_and_prices: Spiele, Tarifgrößen und regionale Preise.
• list_orders.

Sicherheit#

• Werkzeuge, die etwas ändern, sind für deinen Client markiert. Zerstörerische sind als destructiveHint markiert, damit Clients vor der Ausführung nachfragen: Power-Kill, Wiederherstellen, Löschen von Dateien, Backups, Zeitplänen oder Datenbanken, Datenbank-Import, Neuinstallation, Versionswechsel, Modpack-Installation und Überschreiben von Dateien.
• HOSTWOLF_READONLY=1 (oder ?readonly=1 an der gehosteten URL) entfernt alle Werkzeuge, die etwas ändern.
• HOSTWOLF_SERVERS (oder ?servers=) beschränkt den Assistenten auf bestimmte Server.
• Der gehostete Server prüft deinen Schlüssel beim Panel, behält nichts zwischen Anfragen und protokolliert nie Schlüssel oder Werkzeugargumente. Er ist pro Adresse und pro Schlüssel ratenbegrenzt.
• API-Schlüssel können keine Server bestellen, kündigen oder bezahlen. Das geht nur im Web-Panel.
• Du kannst einen eigenen Schlüssel nur für deinen Assistenten erstellen und ihn jederzeit im Panel widerrufen.

Fehlerbehebung#

• „Send your Hostwolf API key“ (401): der Client hat den Header Authorization: Bearer ptlc_... nicht gesendet. Prüfe den Header in deiner Konfiguration.
• „This API key was rejected by the panel“ (401): der Schlüssel ist falsch, unvollständig oder widerrufen. Kopiere den ganzen Schlüssel; er beginnt mit ptlc_.
• „This API key has an IP allow-list…“ (401): der gehostete Server ruft die API von 162.55.180.229 auf. Erstelle einen Schlüssel, der diese Adresse erlaubt, oder einen ohne Freigabeliste, oder betreibe den Server selbst.
• „Too many requests“ (429): der gehostete Server nimmt 300 Anfragen pro Minute je Adresse und 180 je Schlüssel an. Werkzeuge melden auch die eigenen Limits der API, etwa 2 Backups pro 10 Minuten, mit der Wartezeit in Sekunden.
• „Server busy“ (503): versuche es in ein paar Sekunden erneut.
• Eine lange Aufgabe scheint abzubrechen: jedes Werkzeug antwortet innerhalb von 50 Sekunden. Backups, Wiederherstellungen, Neuinstallationen und Modpack-Installationen laufen im Hintergrund weiter. Bitte deinen Assistenten, mit get_server oder list_backups nachzusehen.
• Eine neue Datenbank meldet „wird eingerichtet“: create_database wartet bis zu 2 Minuten (75 Sekunden beim gehosteten Server), bis der Datenbankdienst gestartet ist. Ist er bis dahin nicht bereit, sagt es das, und die Datenbank erscheint kurz danach in list_databases.

Aktualisieren#

Der gehostete Server ist immer aktuell. Beim selbst betriebenen cacht npx den Server nach seiner URL, er aktualisiert sich also nie von selbst. Jede Version hat ihre eigene URL, und der Server prüft beim Start hostwolf.net/dl/index.json. Gibt es eine neuere Version, schreibt er einen Hinweis und hängt ihn an das Ergebnis von list_servers, damit dein Assistent es dir sagt. Zum Aktualisieren änderst du die Version in der URL deiner Konfiguration und startest deinen Client neu.

Auf dem SDK aufgebaut#

Die Werkzeuge nutzen @hostwolf/sdk, das in diesem Paket enthalten ist. Um den Server in deine eigene App einzubetten, installiere beide Pakete:

npm install https://hostwolf.net/dl/hostwolf-sdk-0.1.8.tgz https://hostwolf.net/dl/hostwolf-mcp-0.1.8.tgz

import { Hostwolf } from '@hostwolf/sdk';
import { createHostwolfMcp } from '@hostwolf/mcp/server';

Lizenz#

MIT