@hloth/minecraft-query

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.

Install

• 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

Usage

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 }

API reference

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[];
};

getBasicInfo(arg): Promise<BasicResponse>

Get MOTD, gametype, map, online players, max players and IP address of the server.

getFullInfo(arg): Promise<FullResponse>

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.

License

MIT

Donate

hloth.dev/donate · Tor: hlothdevzkti6suoksy7lcy7hmpxnr3msu5waokzaslsi2mnx5ouu4qd.onion/donate