Mehrere Minecraft-Server mit einer API-Anfrage abfragen

Auf einer Statusseite kann die Lobby erreichbar sein, während ein Spielserver ausfällt. Schicke öffentliche Verbindungsadressen gemeinsam an POST /api/v1/status/bulk. Die Ergebnisse behalten die Eingabereihenfolge und enthalten pro Ziel einen eigenen status_code.

Java und Bedrock gemeinsam abfragen

Speichere den Code als status.mjs und starte ihn mit node status.mjs unter Node.js 22. Der reservierte Name example.invalid zeigt, wie ein nicht erreichbares Ziel neben erfolgreichen Antworten erscheint.

const servers = [
  { address: 'mc.hypixel.net' },
  { address: 'geo.hivebedrock.network', bedrock: true },
  { address: 'example.invalid' },
];

const response = await fetch('https://mcapi.tr/api/v1/status/bulk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ servers }),
  signal: AbortSignal.timeout(15000),
});

if (response.status === 429) {
  throw new Error('Rate limited. Retry-After: ' + (response.headers.get('Retry-After') ?? 'unknown'));
}
if (!response.ok) throw new Error('HTTP ' + response.status);

const { data } = await response.json();
console.table(data.map(({ address, status_code, data: server }) => ({
  address,
  status: status_code === 200 && server.online
    ? (server.stale ? 'stale' : 'online')
    : (status_code === 404 ? 'unreachable' : 'error'),
  players: server.players?.online ?? null,
})));

Jedes Ergebnis einzeln auswerten

• Die HTTP-Antwort kann 200 lauten, obwohl für ein Ziel 404 zurückkommt. Aktualisiere jede Zeile anhand ihres eigenen Ergebnisses.
• Kennzeichne stale: true als zuletzt bekannten Status. Fehlt die Spielerzahl, ist sie unbekannt.
• Pro Anfrage sind bis zu 50 Ziele möglich, pro IP sechs Sammelanfragen je Minute. Wenn viele Besucher dieselbe Liste sehen, frage sie im Backend ab und speichere das Ergebnis kurz zwischen. Berücksichtige bei 429 den Header Retry-After, sofern er vorhanden ist.

Bei Velocity oder BungeeCord verwendest du die öffentliche Proxy-Adresse, über die sich Spieler verbinden. Spielerzahlen privater Paper-Backends für einzelne Spielmodi ermittelst du im eigenen Netzwerk.

Quellen und weitere Anleitungen

• MCAPI-API-Dokumentation
• Spielerzahl auf einer Website anzeigen
• Diskussion in der Community (SpigotMC)