MCAPI.TR Node.js SDK

The official, typed and zero-dependency Node.js client for the MCAPI.TR Minecraft Server Status API.

It supports Java, legacy Java and Bedrock server queries, discovery endpoints, platform statistics, icons, banners and embeddable widgets.

Installation

npm install mcapitr

Node.js 18 or newer is required.

Quick start

const MCAPITR = require("mcapitr");

const api = new MCAPITR();
const status = await api.serverStatus("mc.hypixel.net");

console.log(status.online);
console.log(status.players?.online);

ES modules can use the CommonJS default export:

import MCAPITR from "mcapitr";

const api = new MCAPITR();

Java, Bedrock and legacy queries

const java = await api.serverStatus("mc.hypixel.net");
const bedrock = await api.serverStatus("play.example.net:19132", { bedrock: true });
const legacy = await api.serverStatus("old.example.net", { legacy: true });

The canonical API base URL is https://mcapi.tr/api/v1. Override it or the request timeout when needed:

const api = new MCAPITR({
  baseURL: "https://mcapi.tr/api/v1",
  timeoutMs: 10_000,
});

Discovery and statistics

const health = await api.health();
const firstPage = await api.trends({ limit: 20 });
const statistics = await api.stats();

for (const server of firstPage.data) {
  console.log(server.address, server.players_online);
}

if (firstPage.meta.hasNext) {
  const nextPage = await api.trends({
    limit: 20,
    cursor: firstPage.meta.nextCursor,
  });
}

popularServers(options) remains available for backwards compatibility and returns only the data array from trends(options).

Media URLs and buffers

URL helpers do not make a network request:

const iconUrl = api.serverIcon("mc.hypixel.net", {
  size: 128,
  format: "webp",
});

const bannerUrl = api.serverBanner("mc.hypixel.net", {
  size: "large",
  accentColor: "#10B981",
  showPing: true,
});

const widgetUrl = api.widget("mc.hypixel.net", "large", "dark", {
  showFavicon: true,
  statusIndicator: "badge",
});

const motdUrl = api.motdBanner("&aWelcome to &bMy Server!");

The matching methods download the generated media as a native Buffer:

const icon = await api.serverIconBuffer("mc.hypixel.net", { size: 128 });
const banner = await api.serverBannerBuffer("mc.hypixel.net", { size: "large" });
const motd = await api.motdBannerBuffer("&aWelcome!");

Errors

HTTP, timeout and connection errors are represented by MCAPIError. The error keeps the HTTP status and parsed API response when available.

const { MCAPIError } = require("mcapitr");

try {
  await api.serverStatus("offline.example.net");
} catch (error) {
  if (error instanceof MCAPIError) {
    console.error(error.status, error.message, error.data);
  }
}

TypeScript

Type declarations ship with the package and cover the current status, trends, statistics and media contracts.

import MCAPITR = require("mcapitr");

const api = new MCAPITR();
const server: MCAPITR.ServerStatusResponse = await api.serverStatus("mc.hypixel.net");

License

MIT