Cómo consultar varios servidores de Minecraft en una sola petición

En una red de Minecraft, el lobby puede seguir disponible mientras un modo de juego no responde. Envía las direcciones públicas juntas mediante POST /api/v1/status/bulk. La API mantiene el orden de entrada y devuelve un status_code por destino.

Combina destinos Java y Bedrock

Guarda el ejemplo como status.mjs y ejecuta node status.mjs con Node.js 22. El nombre reservado example.invalid sirve para ver cómo aparece un destino inaccesible junto a los demás resultados.

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,
})));

Interpreta cada resultado por separado

• La petición puede devolver HTTP 200 aunque una dirección tenga status_code: 404. Actualiza cada fila con su propio resultado.
• Indica que el dato es el último conocido si stale es true. Si falta el recuento de jugadores, el valor es desconocido.
• Puedes enviar hasta 50 destinos en una petición y hacer seis peticiones masivas por minuto por IP. Cuando muchos visitantes consulten la misma lista, haz la consulta desde tu backend y reutiliza el resultado durante un intervalo breve. Si recibes 429, respeta Retry-After cuando esté presente.

Si usas Velocity o BungeeCord, consulta las direcciones públicas del proxy. Para obtener los recuentos de cada modo de juego en servidores Paper privados, recoge esos datos dentro de tu propia red.

Fuentes y guías relacionadas

• Documentación de la API de MCAPI
• Mostrar el número de jugadores en una web
• Conversación en la comunidad (SpigotMC)