mc-server-ping

Zero-dependency Minecraft server status checker for Node.js. Supports Java Edition (TCP / Server List Ping) and Bedrock Edition (UDP / RakNet).

Built for Minecraft ServerHub — the free real-time Minecraft server status tool.

Features

• Zero dependencies — uses only Node.js built-ins (net, dgram)
• TypeScript-first — full type definitions included
• Java Edition — full Server List Ping (SLP) protocol over TCP
• Bedrock Edition — RakNet Unconnected Ping/Pong over UDP
• Fast — direct socket implementation, no abstraction overhead
• ESM — modern ES modules with exports field

Installation

npm install mc-server-ping
# or
pnpm add mc-server-ping
# or
bun add mc-server-ping

Quick Start

import { ping } from 'mc-server-ping';

// Java Edition (default)
const result = await ping('play.hypixel.net');
if (result.online) {
  console.log(`Online: ${result.players.online}/${result.players.max} players`);
  console.log(`Version: ${result.version.name}`);
  console.log(`MOTD: ${result.motd}`);
  console.log(`Ping: ${result.ping}ms`);
}

// Bedrock Edition
const bedrock = await ping('play.cubecraft.net', { platform: 'bedrock' });
if (bedrock.online) {
  console.log(`${bedrock.players.online}/${bedrock.players.max} players`);
}

API

ping(host, options?)

Convenience function — pings a server and returns a typed result.

const result = await ping('mc.example.com', {
  platform: 'java',   // 'java' | 'bedrock' — default: 'java'
  port: 25565,        // default: 25565 (java) or 19132 (bedrock)
  timeout: 5000,      // ms — default: 5000
});

Returns: PingResult (Java) or BedrockPingResult (Bedrock)

pingJava(host, port?, timeout?)

Direct Java Edition ping. Uses the Server List Ping protocol.

import { pingJava } from 'mc-server-ping';

const result = await pingJava('play.hypixel.net', 25565, 5000);

if (result.online) {
  // result.version   → { name: string; protocol: number }
  // result.players   → { online: number; max: number; sample?: [...] }
  // result.motd      → string
  // result.favicon   → string (base64 PNG) | undefined
  // result.ping      → number (ms)
}

pingBedrock(host, port?, timeout?)

Bedrock Edition ping via RakNet Unconnected Ping/Pong.

import { pingBedrock } from 'mc-server-ping';

const result = await pingBedrock('play.cubecraft.net', 19132, 5000);

if (result.online) {
  // result.motd      → string
  // result.version   → string
  // result.protocol  → number
  // result.players   → { online: number; max: number }
  // result.gameType  → string
  // result.serverId  → string
  // result.ping      → number (ms)
}

VarInt utilities

The Minecraft protocol uses variable-length integers. These are exported for advanced use cases.

import { writeVarInt, readVarInt } from 'mc-server-ping';

const buf = writeVarInt(300); // → Buffer <AC 02>
const { value, bytesRead } = readVarInt(buf); // → { value: 300, bytesRead: 2 }

How it works

Java Edition — Server List Ping

Java Edition uses a straightforward TCP exchange:

1. Handshake (packet 0x00) — sends protocol version, hostname, port, and next-state = 1 (Status).
2. Status Request (packet 0x00) — empty body, triggers the response.
3. Status Response (packet 0x00) — JSON payload with version, players, MOTD, favicon.
4. Ping/Pong (packet 0x01) — measures round-trip latency.

All integers in packet headers are VarInt-encoded (7 bits per byte, MSB = continuation flag).

Bedrock Edition — RakNet Unconnected Ping

Bedrock uses UDP with the RakNet protocol:

1. Send Unconnected Ping (0x01) — includes RakNet magic bytes and a timestamp.
2. Receive Unconnected Pong (0x1C) — semicolon-delimited string with MOTD, version, player count, and more.

No full RakNet connection handshake is required.

TypeScript types

// Java Edition
interface JavaStatus {
  online: true;
  version: { name: string; protocol: number };
  players: { online: number; max: number; sample?: { name: string; id: string }[] };
  motd: string;
  favicon?: string;
  ping: number;
}

// Bedrock Edition
interface BedrockStatus {
  online: true;
  motd: string;
  gameType: string;
  version: string;
  protocol: number;
  players: { online: number; max: number };
  serverId: string;
  ping: number;
}

// Both return a discriminated union when offline:
interface OfflineStatus {
  online: false;
  error: string;
}

Live demo

Try the interactive server status checker (built with this library) at: minecraft-serverhub.com/tools/server-status-checker

Browse 1,000+ Minecraft servers with real-time status at: minecraft-serverhub.com

License

MIT © Minecraft ServerHub