The fastest lightweight JavaScript wrapper for Minecraft's query protocol. Get MOTD, online players, version and other metadata about Minecraft server in JS. Full TypeScript support, ESM-only, no dependencies, tested on Bun and Node.js v22. Works on Edge.
- Bun:
bun add @hloth/minecraft-query - NPM:
npm install @hloth/minecraft-query - Yarn:
yarn add @hloth/minecraft-query - PNPM:
pnpm add @hloth/minecraft-query - JSR:
jsr install @hloth/minecraft-query
import { getPlayers } from "@hloth/minecraft-query";
const players = await getPlayers("demo.mcstatus.io");
// -> ['player1', 'player2', 'jeb']import { getBasicInfo } from "@hloth/minecraft-query";
const { motd, onlinePlayers, maxPlayers } = await getBasicInfo("demo.mcstatus.io");
// -> { motd: 'A Minecraft Server', onlinePlayers: 0, maxPlayers: 20 }arg can be either a hostname (with default port 25565) or an object of type:
type MinecraftQueryOptions = {
/** Only host, no https protocol. E.g. `example.org`, not `https://example.org` */
hostname: MinecraftHostname;
/** Default is 25565 */
port?: number;
/** Default is 2000ms (2 seconds) */
timeoutMs?: number;
/** Default is 3 */
retries?: number;
};Two types of responses are:
Basic info:
type BasicResponse = {
/** With Minecraft formatting characters */
motd: string;
/** Hardcoded to `SMP` */
gametype: string | null;
/** World name */
map: string;
onlinePlayers: number;
maxPlayers: number;
ipAddress: string;
};and full info:
type FullResponse = BasicResponse & {
/** Everything in BasicResponse and ... */
/** Hardcoded to `MINECRAFT` */
gameId: string;
/** E.g. `1.20.1` */
version: string;
software: string | null;
plugins: string[];
port: number;
players: string[];
};Get MOTD, gametype, map, online players, max players and IP address of the server.
Get MOTD, gametype, map, online players, max players, IP address, game ID, version, server software, plugins, port and list of online players nicknames.
Syntax sugar helpers:
getMotd(): Promise<string>getGametype(): Promise<string | null>getMap(): Promise<string>getOnlinePlayers(): Promise<number>getMaxPlayers(): Promise<number>getIpAddress(): Promise<string>getGameId(): Promise<string>getVersion(): Promise<string>getSoftware(): Promise<string | null>getPlugins(): Promise<string[]>getPort(): Promise<number>getPlayers(): Promise<string[]>
They are making the same getBasicInfo/getFullInfo call under the hood and returning only the requested property. If you need more than one property, consider using getBasicInfo/getFullInfo instead to avoid multiple network calls.
hloth.dev/donate · Tor: hlothdevzkti6suoksy7lcy7hmpxnr3msu5waokzaslsi2mnx5ouu4qd.onion/donate