How to Check Minecraft Server Status with JavaScript (Free API)
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
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}`);
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}`);
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"
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');
const pngUrl = getBadgePngUrl('my-server');
Using the Raw API
If you prefer to call the API directly with fetch:
const res = await fetch('https://minecraft-serverhub.com/api/ping?host=mc.hypixel.net&port=25565&platform=java');
const data = await res.json();
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
Status Page — Build a public status page for your server network
Create Custom MOTDs
Check out the MOTD Creator — a visual editor for Minecraft server MOTDs. 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! 🎮