DEV Community

Draginox
Draginox

Posted on

How to Check Minecraft Server Status with JavaScript (Free API)

#javascript #minecraft #api #webdev

If you're building a Discord bot, a server dashboard, or a status page for your Minecraft community, you probably need a way to check if a server is online and how many players are connected.

In this tutorial, I'll show you how to query any Minecraft server (Java or Bedrock) using a free API and a lightweight npm package — no API key required.

The API

Minecraft ServerHub provides a free REST API for checking Minecraft server status. It supports both Java Edition and Bedrock Edition servers, and returns data like:

  • Online/offline status
  • Player count (current and max)
  • MOTD (Message of the Day)
  • Server version
  • Latency

The full API documentation is here.

Quick Start with the npm Package

I published a zero-dependency wrapper called minecraft-server-status that makes it super easy:

npm install minecraft-server-status
Enter fullscreen mode Exit fullscreen mode

Check a Java Server 

const { getJavaStatus } = require('minecraft-server-status');

const status = await getJavaStatus('mc.hypixel.net');
console.log(`Players: ${status.players.online}/${status.players.max}`);
console.log(`Version: ${status.version}`);
console.log(`MOTD: ${status.motd}`);
Enter fullscreen mode Exit fullscreen mode

Check a Bedrock Server 

const { getBedrockStatus } = require('minecraft-server-status');

const status = await getBedrockStatus('play.example.com', 19132);
console.log(`Online: ${status.online}`);
console.log(`Gamemode: ${status.gamemode}`);
Enter fullscreen mode Exit fullscreen mode

Auto-Detect Platform

Not sure if it's Java or Bedrock? Use getStatus() — it tries Java first, then falls back to Bedrock:

const { getStatus } = require('minecraft-server-status');

const status = await getStatus('play.example.com');
console.log(`Platform: ${status.platform}`); // "java" or "bedrock"
Enter fullscreen mode Exit fullscreen mode

Generate Status Badges

You can also generate embeddable SVG/PNG badges for your README or website:

const { getBadgeUrl, getBadgePngUrl } = require('minecraft-server-status');

const svgUrl = getBadgeUrl('my-server', 'for-the-badge');
// https://minecraft-serverhub.com/api/badges/my-server/svg?style=for-the-badge

const pngUrl = getBadgePngUrl('my-server');
// https://minecraft-serverhub.com/api/badges/my-server/png
Enter fullscreen mode Exit fullscreen mode

Available badge styles: flat, flat-square, for-the-badge

Using the Raw API (No Package Needed)

If you prefer to call the API directly with fetch:

// Java server
const res = await fetch('https://minecraft-serverhub.com/api/ping?host=mc.hypixel.net&port=25565&platform=java');
const data = await res.json();

// Bedrock server
const res2 = await fetch('https://minecraft-serverhub.com/api/ping?host=play.example.com&port=19132&platform=bedrock');
const data2 = await res2.json();
Enter fullscreen mode Exit fullscreen mode

Use Cases

Here are some ideas for what you can build:

  • Discord Bot — Show live player counts in your server
  • Dashboard — Monitor multiple Minecraft servers at once
  • Website Widget — Embed real-time status on your community site
  • CI/CD Check — Verify your server is running after deployment
  • Status Page — Build a public status page for your server network

Create Custom MOTDs

While you're at it, check out the MOTD Creator — a visual editor for Minecraft server MOTDs with color codes and formatting. You can also use the Server Status Checker to check any server directly in your browser.

Links

The API is completely free, no rate limits, no API key. If you have questions or feature requests, open an issue on GitHub.

Happy coding! 🎮

Top comments (0)