DEV Community: Draginox

How to Add Minecraft Server Status to Your GitHub Profile README

Draginox — Wed, 11 Mar 2026 15:53:56 +0000

GitHub profile READMEs are a great way to showcase your projects and interests. If you run a Minecraft server, you can add a live status badge that shows whether your server is online and how many players are connected — all updating automatically. Here's how to set it up in under 5 minutes.

What You'll Get

A dynamic badge in your GitHub profile that shows:

Online/offline status
Current player count
Server version (optional)

The badge updates automatically because it's rendered as an image from the Minecraft ServerHub badge API. GitHub fetches the image each time someone views your profile.

Step 1: Create Your Profile README

If you don't have a profile README yet, create a repository with the same name as your GitHub username. For example, if your username is DraginoxXx, create a repo called DraginoxXx.

Go to GitHub and click New Repository
Name it exactly your username
Check Add a README file
Click Create repository

Now you have a special README that appears on your GitHub profile page.

Step 2: Get Your Badge URL

The Minecraft ServerHub Badge Generator creates badge URLs for any server. The basic format is:

https://minecraft-serverhub.com/api/badge/YOUR_SERVER_ADDRESS

Replace YOUR_SERVER_ADDRESS with your actual server IP or domain. For example:

https://minecraft-serverhub.com/api/badge/play.hypixel.net

Choosing a Style

Three badge styles are available:

Flat (best for GitHub READMEs — matches shields.io badges):

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=flat

Rounded (modern look with smooth corners):

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=rounded

Minecraft (pixel-art style, fun for gaming profiles):

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=minecraft

Adding Options

Customize with query parameters:

Parameter	Example	Effect
`style`	`flat`	Badge visual style
`label`	`My%20Server`	Custom label text
`players`	`true`	Show player count
`version`	`true`	Show MC version
`dark`	`true`	Dark theme

Full example:

https://minecraft-serverhub.com/api/badge/play.myserver.com?style=flat&players=true&label=My%20Server

Use the visual Badge Generator to configure options interactively and get the exact URL.

Step 3: Add to Your README

Edit your profile README and add the badge using Markdown image syntax:

## My Minecraft Server

[![Server Status](https://minecraft-serverhub.com/api/badge/play.myserver.com?style=flat&players=true)](https://minecraft-serverhub.com/server/play.myserver.com)

This creates a clickable badge that links to your server's page on Minecraft ServerHub with full status details.

Complete Profile README Example

Here's a full profile README that includes server status alongside typical GitHub profile content:

# Hi, I'm Alex

Full-stack developer and Minecraft server owner.

## My Projects
- [my-cool-plugin](https://github.com/user/my-cool-plugin) - A custom Minecraft plugin
- [mc-web-panel](https://github.com/user/mc-web-panel) - Server management dashboard

## My Minecraft Server

[![Server Status](https://minecraft-serverhub.com/api/badge/play.myserver.com?style=flat&players=true)](https://minecraft-serverhub.com/server/play.myserver.com)

Join us at `play.myserver.com` - A survival community with custom plugins!

## Tech Stack

![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
![Next.js](https://img.shields.io/badge/-Next.js-000?logo=next.js)
![PostgreSQL](https://img.shields.io/badge/-PostgreSQL-4169E1?logo=postgresql&logoColor=white)

Step 4: Add Multiple Server Badges

If you run a network with multiple servers, display them all:

## Our Server Network

| Server | Status |
|--------|--------|
| Hub | [![Hub](https://minecraft-serverhub.com/api/badge/hub.mynetwork.com?style=flat)](https://minecraft-serverhub.com/server/hub.mynetwork.com) |
| Survival | [![Survival](https://minecraft-serverhub.com/api/badge/survival.mynetwork.com?style=flat)](https://minecraft-serverhub.com/server/survival.mynetwork.com) |
| Creative | [![Creative](https://minecraft-serverhub.com/api/badge/creative.mynetwork.com?style=flat)](https://minecraft-serverhub.com/server/creative.mynetwork.com) |

Adding to Project READMEs

Server status badges also work great in Minecraft plugin or mod READMEs:

# My Minecraft Plugin

[![Build](https://img.shields.io/github/actions/workflow/status/user/repo/build.yml)](https://github.com/user/repo/actions)
[![Downloads](https://img.shields.io/github/downloads/user/repo/total)](https://github.com/user/repo/releases)
[![Test Server](https://minecraft-serverhub.com/api/badge/test.myserver.com?style=flat&label=Test%20Server)](https://minecraft-serverhub.com/server/test.myserver.com)

A custom plugin that adds awesome features to your server.

Using the npm Package

If you're building a tool that generates READMEs or documentation programmatically, use the minecraft-server-badge npm package:

const { markdown } = require("minecraft-server-badge");

// Generate Markdown badge code
const badge = markdown("play.myserver.com", {
  style: "flat",
  players: true,
  label: "My Server"
});

console.log(badge);
// [![My Server](https://minecraft-serverhub.com/api/badge/play.myserver.com?style=flat&players=true&label=My%20Server)](https://minecraft-serverhub.com/server/play.myserver.com)

How It Works

The badge is an SVG image served by the Minecraft ServerHub API. When someone views your profile:

GitHub's Markdown renderer requests the badge image URL
Minecraft ServerHub checks the server status (cached for 5 minutes)
An SVG badge is generated with current data
The badge renders in the browser

Since it's a standard image URL, it works everywhere Markdown is rendered — GitHub, GitLab, Bitbucket, dev.to, and any documentation site.

Troubleshooting

Badge shows "offline" but server is online:

Make sure the address is correct and accessible from the internet
The API caches results for 5 minutes, so recent startups may take a moment
Check your server's status directly at minecraft-serverhub.com

Badge not updating:

GitHub caches images aggressively. Add a cache-busting parameter if needed
Try viewing in an incognito window to bypass browser cache

Want a different look?

Use the Badge Generator to try different styles
The minecraft style looks especially fun on gaming-related profiles

More Minecraft Developer Resources

Minecraft ServerHub — Server discovery and monitoring platform
API Documentation — Build integrations with the free REST API
MOTD Creator — Design server MOTDs visually
Server Statistics — Ecosystem-wide player data
Server Explorer — Browse 5000+ active servers

Badges powered by Minecraft ServerHub — free tools for the Minecraft community.

5 Free APIs Every Minecraft Developer Should Know About

Draginox — Wed, 11 Mar 2026 15:51:27 +0000

Whether you're building a Discord bot, a server status page, or a Minecraft plugin companion app, you need APIs. Here are 5 free APIs that every Minecraft developer should have in their toolkit — all with code examples.

1. Minecraft ServerHub API — Server Status & Monitoring

What it does: Query any Java or Bedrock Minecraft server for real-time status data including player count, MOTD, version, latency, and server icon.

Why it's useful: The most common thing Minecraft developers need is server status data. This API provides it for any server without authentication.

Base URL: https://minecraft-serverhub.com/api

Example — Check server status:

async function checkServer(address) {
  const res = await fetch("https://minecraft-serverhub.com/api/server/" + address);
  const data = await res.json();
  console.log("Online:", data.online);
  console.log("Players:", data.players.online + "/" + data.players.max);
  console.log("Version:", data.version);
  console.log("MOTD:", data.motd.clean);
  return data;
}

checkServer("play.hypixel.net");

Example — Generate a status badge:

// Returns an SVG image URL you can embed anywhere
const badgeUrl = "https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=flat&players=true";

Bonus features:

Interactive badge generator for creating embeddable status images
MOTD Creator for building formatted server descriptions
Server explorer with 5000+ indexed servers
Full API docs

Rate limit: Generous, no API key needed.

2. Mojang API — Player Profiles & UUIDs

What it does: Look up Minecraft player profiles, convert usernames to UUIDs, and fetch player skin data.

Why it's useful: Almost every Minecraft tool needs to resolve player names to UUIDs or display player skins/heads.

Example — Username to UUID:

async function getUUID(username) {
  const res = await fetch("https://api.mojang.com/users/profiles/minecraft/" + username);
  if (!res.ok) return null;
  const data = await res.json();
  return data.id; // UUID without dashes
}

// Returns something like "069a79f444e94726a5befca90e38aaf5"
getUUID("Notch").then(console.log);

Example — Get skin texture URL:

async function getSkinUrl(uuid) {
  const res = await fetch("https://sessionserver.mojang.com/session/minecraft/profile/" + uuid);
  const data = await res.json();
  const props = JSON.parse(atob(data.properties[0].value));
  return props.textures.SKIN.url;
}

Rate limit: 600 requests per 10 minutes.

3. Crafatar — Player Avatars & Renders

What it does: Generates player head renders, full body renders, and skin images from UUIDs. No API key needed.

Why it's useful: Displaying player avatars in your Discord bot, website, or dashboard. Perfect companion to the Minecraft ServerHub player data.

Example — Player head image:

<!-- 64x64 player head -->
<img src="https://crafatar.com/avatars/069a79f444e94726a5befca90e38aaf5?size=64" alt="Notch" />

<!-- Full body render -->
<img src="https://crafatar.com/renders/body/069a79f444e94726a5befca90e38aaf5?scale=4" alt="Notch" />

Example — In JavaScript:

function getPlayerHead(uuid, size) {
  return "https://crafatar.com/avatars/" + uuid + "?size=" + (size || 64) + "&overlay";
}

Rate limit: Reasonable, cached responses.

4. MCStatus.io — Backup Status Checker

What it does: Another server status API with slightly different data formatting. Good as a fallback.

Why it's useful: Having a backup API ensures your bot or app stays functional even if one service has downtime. Use alongside the Minecraft ServerHub API for redundancy.

Example:

async function checkServerBackup(address) {
  const res = await fetch("https://api.mcstatus.io/v2/status/java/" + address);
  const data = await res.json();
  return {
    online: data.online,
    players: data.players ? data.players.online : 0,
  };
}

Tip: For production apps, query Minecraft ServerHub first and fall back to MCStatus.io if needed:

async function getStatus(address) {
  try {
    const res = await fetch("https://minecraft-serverhub.com/api/server/" + address);
    if (res.ok) return await res.json();
  } catch (e) {}

  // Fallback
  const res = await fetch("https://api.mcstatus.io/v2/status/java/" + address);
  return await res.json();
}

5. CraftHead — Fast Head Renders via Cloudflare Workers

What it does: Ultra-fast player head renders served through Cloudflare's edge network.

Why it's useful: When you need the fastest possible player avatars for high-traffic applications.

Example:

<img src="https://crafthead.net/avatar/069a79f444e94726a5befca90e38aaf5/64" alt="Player head" />

Putting It All Together

Here's a real-world example that combines multiple APIs to build a server status widget:

async function buildServerWidget(address) {
  // Get server status from Minecraft ServerHub
  const serverRes = await fetch("https://minecraft-serverhub.com/api/server/" + address);
  const server = await serverRes.json();

  if (!server.online) {
    return { status: "offline", badge: "https://minecraft-serverhub.com/api/badge/" + address };
  }

  // Get player heads for online players (if player list available)
  const playerHeads = [];
  if (server.players.list) {
    for (const player of server.players.list.slice(0, 5)) {
      playerHeads.push({
        name: player.name,
        head: "https://crafatar.com/avatars/" + player.id + "?size=32&overlay",
      });
    }
  }

  return {
    status: "online",
    players: server.players.online + "/" + server.players.max,
    version: server.version,
    motd: server.motd.clean,
    badge: "https://minecraft-serverhub.com/api/badge/" + address + "?style=flat",
    playerHeads: playerHeads,
  };
}

Comparison Table

API	Auth Required	Rate Limit	Best For
Minecraft ServerHub	No	Generous	Server status, badges, monitoring
Mojang API	No	600/10min	Player UUIDs, profiles
Crafatar	No	Reasonable	Player avatars
MCStatus.io	No	Moderate	Backup status checks
CraftHead	No	High	Fast avatar renders

Which API Should You Use?

Building a Discord bot? Start with Minecraft ServerHub for server status + Crafatar for player heads
Building a website? Use Minecraft ServerHub badges for status images + Mojang API for player data
Building a dashboard? Combine Minecraft ServerHub status + history endpoints with Chart.js for analytics
Building a plugin companion? Use Mojang API for auth + Minecraft ServerHub for cross-server data

Resources

Minecraft ServerHub — Server monitoring platform with free API
Minecraft ServerHub API Docs — Full endpoint documentation
Badge Generator — Create embeddable status badges
Server Statistics — Live ecosystem data
npm: minecraft-server-badge — Badge generation package

Server status data powered by Minecraft ServerHub — free tools and APIs for the Minecraft developer community.

Open Source Minecraft Server Tools: Why We Built ServerHub and What We Learned

Draginox — Wed, 11 Mar 2026 15:48:54 +0000

I've been working on Minecraft ServerHub for several months — an open-source platform that monitors 5000+ Minecraft servers and provides free developer tools. Here's why we built it, the technical decisions we made, and what we learned along the way.

The Problem

Minecraft has 170+ million active players, and there are thousands of community-run multiplayer servers. But the tooling around these servers is fragmented:

Server owners need monitoring, analytics, and status pages
Players need a reliable way to find and check servers
Developers need APIs to build bots, dashboards, and integrations

Existing solutions were either outdated, closed-source, or charged for basic features that should be free.

The Stack

We chose a modern, production-grade stack:

Next.js 15 with App Router for the frontend and API routes
TypeScript throughout the entire codebase
PostgreSQL for structured data (servers, players, history)
Redis for caching and real-time data
Tailwind CSS for styling
Cloudflare for CDN and DDoS protection

The source code is on GitHub and the live platform runs at minecraft-serverhub.com.

Architecture Decisions

Why Next.js for a Server Monitoring Platform?

Server-side rendering matters for SEO. We want every server page to be indexable by search engines so players can find servers through Google. With Next.js App Router, each server page at /server/[address] is server-rendered with fresh data.

The API routes handle the heavy lifting:

/api/server/[address]     - Server status (JSON)
/api/badge/[address]      - Status badge (SVG)
/api/server/[address]/history - Historical data

Check the full API documentation for all available endpoints.

The Minecraft Protocol Challenge

Minecraft uses a custom TCP protocol for server queries. The implementation handles:

Handshake packet — Establish connection with protocol version
Status request — Ask for server info (SLP - Server List Ping)
Response parsing — Decode the JSON response with player data, MOTD, version, and favicon

For Bedrock servers, it's completely different — they use UDP with the RakNet protocol. We had to implement both query methods to support the full Minecraft ecosystem.

Database Design for 5000+ Servers

With servers being pinged every 5 minutes, the database grows fast. Our schema prioritizes query speed for the most common operations:

-- Servers table with denormalized current status
CREATE TABLE servers (
  id SERIAL PRIMARY KEY,
  address VARCHAR(255) UNIQUE NOT NULL,
  platform VARCHAR(10) NOT NULL, -- 'java' or 'bedrock'
  online BOOLEAN DEFAULT false,
  players_online INTEGER DEFAULT 0,
  players_max INTEGER DEFAULT 0,
  version VARCHAR(100),
  motd_clean TEXT,
  motd_raw TEXT,
  last_ping TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

-- History snapshots for analytics
CREATE TABLE server_history (
  id BIGSERIAL PRIMARY KEY,
  server_id INTEGER REFERENCES servers(id),
  players_online INTEGER,
  latency INTEGER,
  online BOOLEAN,
  recorded_at TIMESTAMP DEFAULT NOW()
);

-- Indexes for common queries
CREATE INDEX idx_history_server_time ON server_history(server_id, recorded_at DESC);
CREATE INDEX idx_servers_players ON servers(players_online DESC) WHERE online = true;

You can see the real-time results of this data on the statistics dashboard, which aggregates player counts across the entire ecosystem.

Caching Strategy

Redis sits between the API and the database:

Request -> Redis Cache -> Database
              |
              v
         5-min TTL for status
         1-hour TTL for metadata
         24-hour TTL for history aggregates

For the badge API, caching is critical. Badges are embedded as images across hundreds of websites and forums. Without caching, a popular server's badge could generate thousands of requests per minute.

Developer Tools We Built

1. REST API

The free API requires no authentication. It returns JSON data for any server:

const res = await fetch("https://minecraft-serverhub.com/api/server/play.hypixel.net");
const data = await res.json();
// { online: true, players: { online: 45000, max: 200000 }, version: "1.8-1.20", ... }

2. npm Package

We published minecraft-server-badge for generating badge embed codes programmatically:

npm install minecraft-server-badge

3. MOTD Creator

The MOTD Creator is a visual editor for Minecraft's special text formatting system. Server owners use it to design their server's greeting message with colors and styles.

4. Badge Generator

The Badge Generator creates embeddable status images in three styles (rounded, flat, minecraft) with customizable options.

5. Server Explorer

The explorer lets players browse servers by gamemode, version, and region. It indexes categories like survival, creative, PvP, minigames, and more.

Lessons Learned

1. Minecraft Protocol Versions Are a Nightmare

Every Minecraft version changes the protocol slightly. Version 1.7 introduced the modern SLP system, but older servers still respond differently. We handle protocol versions from 1.7 through the latest snapshot, and each needs testing.

2. Server Owners Care About Uptime More Than Features

Our most-used feature isn't the fancy explorer or analytics — it's the simple status check. The "is my server online right now?" question drives 60% of our traffic. We learned to optimize for this use case first.

3. Open Source Builds Trust

Making the source code available on GitHub helped build trust with the Minecraft community. Server owners are understandably cautious about giving third-party tools access to their server data, even if it's just a status ping. Open source removes that barrier.

4. SVG Badges Are Surprisingly Complex

Generating pixel-perfect SVG badges that look correct across all platforms was harder than expected. Different renderers handle fonts, padding, and anti-aliasing differently. We ended up with a custom SVG generator that accounts for these differences.

5. The Minecraft Community Is Enormous and Active

With over 5000 active servers in our index and growing, the scale of the Minecraft multiplayer ecosystem is impressive. The community is also technically savvy — many server owners write their own plugins and want API access rather than just a web UI.

What's Next

We're working on several improvements:

Historical analytics — Longer-term trend data for server owners
Alerting — Email and webhook notifications for downtime
Plugin integration — Direct integration with Spigot/Paper plugins
Community features — Reviews, ratings, and server recommendations

Try It Out

Platform: minecraft-serverhub.com
API Docs: minecraft-serverhub.com/developers
Tools: MOTD Creator, Badge Generator
Statistics: minecraft-serverhub.com/statistics
Explorer: minecraft-serverhub.com/explore
GitHub: github.com/DraginoxXx/minecraft-server-status
npm: minecraft-server-badge

Everything is free and open source. If you run a Minecraft server or build tools for the community, give it a try and let me know what you think.

Minecraft ServerHub — free, open-source Minecraft server monitoring and developer tools.

Minecraft Server Analytics: Tracking Player Trends with Chart.js and REST APIs

Draginox — Wed, 11 Mar 2026 15:46:18 +0000

Understanding player activity patterns is key to running a successful Minecraft server. When do players log on? Which servers are growing? How does your server compare to others? In this tutorial, we'll build a player analytics dashboard using Chart.js and the Minecraft ServerHub API.

What We're Building

A single-page dashboard that shows:

Real-time player count for any server
Historical player trend chart
Comparison view for multiple servers
Peak hours analysis

All data comes from the free Minecraft ServerHub REST API, which tracks 5000+ servers and provides historical snapshots.

Project Setup

We'll keep this simple with vanilla HTML and JavaScript. No build tools needed.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>MC Server Analytics</title>
  <script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: system-ui, sans-serif; background: #0f0f0f; color: #e5e5e5; padding: 2rem; }
    .card { background: #1a1a1a; border-radius: 12px; padding: 1.5rem; margin-bottom: 1.5rem; }
    h1 { font-size: 1.75rem; margin-bottom: 0.5rem; }
    .subtitle { color: #888; margin-bottom: 2rem; }
    .subtitle a { color: #60a5fa; text-decoration: none; }
    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 1rem; margin-bottom: 1.5rem; }
    .stat { text-align: center; }
    .stat-value { font-size: 2rem; font-weight: bold; color: #22c55e; }
    .stat-label { color: #888; font-size: 0.875rem; }
    input { background: #262626; border: 1px solid #333; color: white; padding: 0.5rem 1rem; border-radius: 8px; font-size: 1rem; }
    button { background: #22c55e; color: black; border: none; padding: 0.5rem 1.5rem; border-radius: 8px; font-size: 1rem; cursor: pointer; font-weight: 600; }
    button:hover { background: #16a34a; }
    canvas { max-height: 400px; }
  </style>
</head>
<body>
  <h1>Minecraft Server Analytics</h1>
  <p class="subtitle">
    Powered by <a href="https://minecraft-serverhub.com">Minecraft ServerHub</a> |
    <a href="https://minecraft-serverhub.com/developers">API Docs</a>
  </p>

  <div class="card">
    <input id="serverInput" type="text" placeholder="Enter server address (e.g. play.hypixel.net)" />
    <button onclick="loadServer()">Track</button>
  </div>

  <div class="grid" id="statsGrid"></div>

  <div class="card">
    <canvas id="playerChart"></canvas>
  </div>

  <div class="card">
    <canvas id="compareChart"></canvas>
  </div>

  <script src="app.js"></script>
</body>
</html>

Step 1: Fetching Server Data

The Minecraft ServerHub API provides server status at a simple endpoint. Here's our data layer:

// app.js
const API_BASE = "https://minecraft-serverhub.com/api";

async function fetchServerStatus(address) {
  const response = await fetch(API_BASE + "/server/" + address);
  if (!response.ok) throw new Error("Server not found");
  return response.json();
}

async function fetchServerHistory(address) {
  // Fetch historical snapshots for trend analysis
  const response = await fetch(API_BASE + "/server/" + address + "/history");
  if (!response.ok) return [];
  const data = await response.json();
  return data.snapshots || [];
}

Step 2: Displaying Real-Time Stats

Create stat cards that show current server metrics:

function renderStats(server, address) {
  const grid = document.getElementById("statsGrid");
  const stats = [
    { label: "Status", value: server.online ? "ONLINE" : "OFFLINE", color: server.online ? "#22c55e" : "#ef4444" },
    { label: "Players", value: server.online ? server.players.online + "/" + server.players.max : "N/A", color: "#60a5fa" },
    { label: "Version", value: server.version || "Unknown", color: "#a78bfa" },
    { label: "Latency", value: server.online ? server.latency + "ms" : "N/A", color: "#f59e0b" },
  ];

  grid.innerHTML = stats.map(function(s) {
    return '<div class="card stat">' +
      '<div class="stat-value" style="color:' + s.color + '">' + s.value + '</div>' +
      '<div class="stat-label">' + s.label + '</div>' +
      '</div>';
  }).join("");
}

Step 3: Building the Player Count Chart

This is the core visualization. We use Chart.js to render player count over time:

let playerChart = null;

function renderPlayerChart(history, address) {
  const ctx = document.getElementById("playerChart").getContext("2d");

  if (playerChart) playerChart.destroy();

  const labels = history.map(function(h) {
    return new Date(h.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
  });

  const playerData = history.map(function(h) {
    return h.players ? h.players.online : 0;
  });

  playerChart = new Chart(ctx, {
    type: "line",
    data: {
      labels: labels,
      datasets: [{
        label: address + " - Players Online",
        data: playerData,
        borderColor: "#22c55e",
        backgroundColor: "rgba(34, 197, 94, 0.1)",
        fill: true,
        tension: 0.3,
        pointRadius: 2,
      }]
    },
    options: {
      responsive: true,
      plugins: {
        legend: { labels: { color: "#e5e5e5" } },
        title: {
          display: true,
          text: "Player Count Over Time",
          color: "#e5e5e5",
          font: { size: 16 }
        }
      },
      scales: {
        x: { ticks: { color: "#888" }, grid: { color: "#262626" } },
        y: { ticks: { color: "#888" }, grid: { color: "#262626" }, beginAtZero: true }
      }
    }
  });
}

Step 4: Server Comparison View

Let server owners compare their player counts against popular servers. We'll track multiple servers on one chart:

let compareChart = null;
const trackedServers = [];
const chartColors = ["#22c55e", "#60a5fa", "#f59e0b", "#ef4444", "#a78bfa"];

async function addToComparison(address) {
  if (trackedServers.length >= 5) return;

  const status = await fetchServerStatus(address);
  trackedServers.push({
    address: address,
    players: status.online ? status.players.online : 0,
    max: status.online ? status.players.max : 0,
  });

  renderCompareChart();
}

function renderCompareChart() {
  const ctx = document.getElementById("compareChart").getContext("2d");

  if (compareChart) compareChart.destroy();

  compareChart = new Chart(ctx, {
    type: "bar",
    data: {
      labels: trackedServers.map(function(s) { return s.address; }),
      datasets: [{
        label: "Current Players",
        data: trackedServers.map(function(s) { return s.players; }),
        backgroundColor: trackedServers.map(function(s, i) { return chartColors[i]; }),
        borderRadius: 6,
      }, {
        label: "Max Capacity",
        data: trackedServers.map(function(s) { return s.max; }),
        backgroundColor: trackedServers.map(function(s, i) { return chartColors[i] + "33"; }),
        borderRadius: 6,
      }]
    },
    options: {
      responsive: true,
      plugins: {
        legend: { labels: { color: "#e5e5e5" } },
        title: {
          display: true,
          text: "Server Comparison",
          color: "#e5e5e5",
          font: { size: 16 }
        }
      },
      scales: {
        x: { ticks: { color: "#888" }, grid: { color: "#262626" } },
        y: { ticks: { color: "#888" }, grid: { color: "#262626" }, beginAtZero: true }
      }
    }
  });
}

Step 5: Tying It All Together

The main load function that orchestrates everything:

async function loadServer() {
  const input = document.getElementById("serverInput");
  const address = input.value.trim();
  if (!address) return;

  try {
    const status = await fetchServerStatus(address);
    renderStats(status, address);

    const history = await fetchServerHistory(address);
    if (history.length > 0) {
      renderPlayerChart(history, address);
    }

    await addToComparison(address);
    input.value = "";
  } catch (err) {
    alert("Could not load server: " + err.message);
  }
}

// Load a popular server by default
window.addEventListener("DOMContentLoaded", function() {
  document.getElementById("serverInput").value = "play.hypixel.net";
  loadServer();
});

Adding Auto-Refresh

Keep the dashboard live with periodic updates:

let currentAddress = null;

setInterval(async function() {
  if (!currentAddress) return;
  try {
    const status = await fetchServerStatus(currentAddress);
    renderStats(status, currentAddress);
  } catch (e) {
    console.error("Refresh failed:", e);
  }
}, 60000); // Every 60 seconds

Peak Hours Analysis

One of the most useful analytics features is knowing when player activity peaks. The Minecraft ServerHub statistics page shows ecosystem-wide trends, but you can also calculate this per-server:

function analyzePeakHours(history) {
  const hourBuckets = {};
  for (let i = 0; i < 24; i++) hourBuckets[i] = [];

  history.forEach(function(snapshot) {
    const hour = new Date(snapshot.timestamp).getHours();
    if (snapshot.players) {
      hourBuckets[hour].push(snapshot.players.online);
    }
  });

  const averages = {};
  Object.keys(hourBuckets).forEach(function(hour) {
    const values = hourBuckets[hour];
    if (values.length > 0) {
      averages[hour] = Math.round(values.reduce(function(a, b) { return a + b; }, 0) / values.length);
    } else {
      averages[hour] = 0;
    }
  });

  return averages;
}

This gives server owners actionable data: schedule events during peak hours, plan maintenance during low-activity periods, and understand their player base's timezone distribution.

Discovering Servers to Analyze

Need servers to test with? The Minecraft ServerHub explorer lists 5000+ active servers organized by gamemode, version, and player count. You can find servers across categories:

Survival servers — The classic gameplay experience
Creative servers — Building and design communities
PvP servers — Competitive gameplay
Minigame servers — Game networks and hubs

Each server page on Minecraft ServerHub already shows player history charts, making it easy to verify your dashboard's data against the platform's own analytics.

Deploying Your Dashboard

Since it's just HTML + JS, deploy anywhere:

# GitHub Pages
git init && git add . && git commit -m "analytics dashboard"
gh repo create mc-analytics --public --source=. --push

# Or use any static host: Vercel, Netlify, Cloudflare Pages

What's Next?

Some ideas for extending the dashboard:

SQLite storage — Save snapshots locally for long-term trend analysis
Email alerts — Notify when player count drops below a threshold
Webhook integrations — Post analytics summaries to Discord
Export to CSV — Let server owners export their data
Embeddable widgets — Create iframe-ready components using the badge API

Conclusion

Building analytics tools for Minecraft servers is a great way to learn data visualization while solving a real problem for server communities. The Minecraft ServerHub API makes it easy to get started — no API key needed, just fetch and display.

For production-ready analytics with historical data and trend analysis, visit the Minecraft ServerHub statistics dashboard which already tracks the entire Minecraft server ecosystem.

Built with Minecraft ServerHub — free server monitoring, analytics, and developer tools for Minecraft.

Building a Minecraft Server MOTD Editor with React and Tailwind CSS

Draginox — Wed, 11 Mar 2026 15:43:36 +0000

Minecraft servers use a "Message of the Day" (MOTD) to greet players in the server list. These messages support a special formatting system with color codes and styling. In this tutorial, we'll build a visual MOTD editor using React and Tailwind CSS, inspired by the MOTD Creator tool on Minecraft ServerHub.

Understanding Minecraft MOTD Formatting

Minecraft uses a section sign followed by a format code for styling. Here are the available codes:

Code	Color	Code	Style
0	Black	l	Bold
1	Dark Blue	m	Strikethrough
2	Dark Green	n	Underline
3	Dark Aqua	o	Italic
4	Dark Red	r	Reset
5	Dark Purple
6	Gold
7	Gray
8	Dark Gray
9	Blue
a	Green
b	Aqua
c	Red
d	Light Purple
e	Yellow
f	White

A typical MOTD looks like this: a color code followed by text, another color code followed by more text, and so on. The Minecraft ServerHub MOTD Creator lets you build these visually and see a real-time preview.

Project Setup

npx create-react-app motd-editor
cd motd-editor
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Configure Tailwind in tailwind.config.js:

module.exports = {
  content: ["./src/**/*.js"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Step 1: Define the Color Map

Create a mapping from Minecraft color codes to CSS colors:

// src/colors.js
const MC_COLORS = {
  "0": { name: "Black", hex: "#000000" },
  "1": { name: "Dark Blue", hex: "#0000AA" },
  "2": { name: "Dark Green", hex: "#00AA00" },
  "3": { name: "Dark Aqua", hex: "#00AAAA" },
  "4": { name: "Dark Red", hex: "#AA0000" },
  "5": { name: "Dark Purple", hex: "#AA00AA" },
  "6": { name: "Gold", hex: "#FFAA00" },
  "7": { name: "Gray", hex: "#AAAAAA" },
  "8": { name: "Dark Gray", hex: "#555555" },
  "9": { name: "Blue", hex: "#5555FF" },
  "a": { name: "Green", hex: "#55FF55" },
  "b": { name: "Aqua", hex: "#55FFFF" },
  "c": { name: "Red", hex: "#FF5555" },
  "d": { name: "Light Purple", hex: "#FF55FF" },
  "e": { name: "Yellow", hex: "#FFFF55" },
  "f": { name: "White", hex: "#FFFFFF" },
};

export default MC_COLORS;

Step 2: Build the MOTD Parser

The parser converts a MOTD string with format codes into an array of styled segments:

// src/parser.js
import MC_COLORS from "./colors";

export function parseMOTD(text) {
  const segments = [];
  let current = { text: "", color: "#AAAAAA", bold: false, italic: false, underline: false, strikethrough: false };

  const chars = text.split("");
  let i = 0;

  while (i < chars.length) {
    // Check for section sign or ampersand as format prefix
    if ((chars[i] === "\u00A7" || chars[i] === "&") && i + 1 < chars.length) {
      const code = chars[i + 1].toLowerCase();

      if (current.text) {
        segments.push({ ...current });
        current = { ...current, text: "" };
      }

      if (MC_COLORS[code]) {
        current.color = MC_COLORS[code].hex;
        current.bold = false;
        current.italic = false;
        current.underline = false;
        current.strikethrough = false;
      } else if (code === "l") current.bold = true;
      else if (code === "o") current.italic = true;
      else if (code === "n") current.underline = true;
      else if (code === "m") current.strikethrough = true;
      else if (code === "r") {
        current.color = "#AAAAAA";
        current.bold = false;
        current.italic = false;
        current.underline = false;
        current.strikethrough = false;
      }

      i += 2;
    } else {
      current.text += chars[i];
      i++;
    }
  }

  if (current.text) segments.push(current);
  return segments;
}

Step 3: Create the Preview Component

This component renders parsed MOTD segments with proper styling on a dark background that mimics the Minecraft server list:

// src/MOTDPreview.js
import { parseMOTD } from "./parser";

function MOTDPreview({ text }) {
  const segments = parseMOTD(text);

  return (
    <div className="bg-zinc-900 p-6 rounded-lg font-mono text-lg min-h-16">
      {segments.map(function(seg, i) {
        const style = {
          color: seg.color,
          fontWeight: seg.bold ? "bold" : "normal",
          fontStyle: seg.italic ? "italic" : "normal",
          textDecoration: [
            seg.underline ? "underline" : "",
            seg.strikethrough ? "line-through" : "",
          ].filter(Boolean).join(" ") || "none",
        };
        return <span key={i} style={style}>{seg.text}</span>;
      })}
    </div>
  );
}

export default MOTDPreview;

Step 4: Build the Color Palette

A clickable color palette that inserts format codes into the editor:

// src/ColorPalette.js
import MC_COLORS from "./colors";

function ColorPalette({ onSelect }) {
  return (
    <div className="flex flex-wrap gap-1 mb-4">
      {Object.entries(MC_COLORS).map(function(entry) {
        const code = entry[0];
        const data = entry[1];
        return (
          <button
            key={code}
            onClick={function() { onSelect(code); }}
            className="w-8 h-8 rounded border border-zinc-600 hover:scale-110 transition-transform"
            style={{ backgroundColor: data.hex }}
            title={data.name + " (&" + code + ")"}
          />
        );
      })}
      <button
        onClick={function() { onSelect("l"); }}
        className="px-2 h-8 rounded border border-zinc-600 bg-zinc-800 text-white font-bold hover:bg-zinc-700"
        title="Bold (&l)"
      >
        B
      </button>
      <button
        onClick={function() { onSelect("o"); }}
        className="px-2 h-8 rounded border border-zinc-600 bg-zinc-800 text-white italic hover:bg-zinc-700"
        title="Italic (&o)"
      >
        I
      </button>
      <button
        onClick={function() { onSelect("n"); }}
        className="px-2 h-8 rounded border border-zinc-600 bg-zinc-800 text-white underline hover:bg-zinc-700"
        title="Underline (&n)"
      >
        U
      </button>
      <button
        onClick={function() { onSelect("r"); }}
        className="px-2 h-8 rounded border border-zinc-600 bg-zinc-800 text-white hover:bg-zinc-700"
        title="Reset (&r)"
      >
        R
      </button>
    </div>
  );
}

export default ColorPalette;

Step 5: Assemble the Editor

Bring everything together in the main App component:

// src/App.js
import { useState, useRef } from "react";
import MOTDPreview from "./MOTDPreview";
import ColorPalette from "./ColorPalette";

function App() {
  const [motd, setMotd] = useState("&6Welcome to &lMy Server&r\n&7Play now!");
  const textareaRef = useRef(null);

  function insertCode(code) {
    const ta = textareaRef.current;
    const start = ta.selectionStart;
    const end = ta.selectionEnd;
    const newText = motd.substring(0, start) + "&" + code + motd.substring(end);
    setMotd(newText);
    setTimeout(function() {
      ta.selectionStart = start + 2;
      ta.selectionEnd = start + 2;
      ta.focus();
    }, 0);
  }

  function copyToClipboard() {
    navigator.clipboard.writeText(motd.replace(/&([0-9a-fl-or])/g, "\u00A7$1"));
  }

  return (
    <div className="min-h-screen bg-zinc-950 text-white p-8">
      <div className="max-w-2xl mx-auto">
        <h1 className="text-3xl font-bold mb-2">MOTD Editor</h1>
        <p className="text-zinc-400 mb-6">
          Build your Minecraft server MOTD with a visual editor.
          Try the full-featured version at the{" "}
          <a href="https://minecraft-serverhub.com/tools/motd-creator"
             className="text-blue-400 hover:underline">
            Minecraft ServerHub MOTD Creator
          </a>.
        </p>

        <ColorPalette onSelect={insertCode} />

        <textarea
          ref={textareaRef}
          value={motd}
          onChange={function(e) { setMotd(e.target.value); }}
          className="w-full bg-zinc-800 border border-zinc-700 rounded-lg p-4 font-mono text-sm mb-4 resize-none"
          rows={4}
          placeholder="Type your MOTD here using & color codes..."
        />

        <h2 className="text-lg font-semibold mb-2">Preview</h2>
        <MOTDPreview text={motd} />

        <div className="mt-4 flex gap-2">
          <button
            onClick={copyToClipboard}
            className="bg-emerald-600 hover:bg-emerald-700 px-4 py-2 rounded font-medium"
          >
            Copy MOTD
          </button>
          <button
            onClick={function() { setMotd(""); }}
            className="bg-zinc-700 hover:bg-zinc-600 px-4 py-2 rounded font-medium"
          >
            Clear
          </button>
        </div>
      </div>
    </div>
  );
}

export default App;

Step 6: Add server.properties Export

Most server owners need the MOTD in their server.properties file. Add an export function:

function exportForServerProperties() {
  // Convert & codes to section signs for server.properties
  const converted = motd
    .replace(/&([0-9a-fl-or])/g, "\\u00A7$1")
    .replace(/\n/g, "\\n");
  navigator.clipboard.writeText("motd=" + converted);
}

Testing with Real Server Data

To see how your MOTD looks compared to real servers, you can query the Minecraft ServerHub API and display actual server MOTDs:

async function loadRealMOTD(address) {
  const res = await fetch("https://minecraft-serverhub.com/api/server/" + address);
  const data = await res.json();
  if (data.motd && data.motd.raw) {
    setMotd(data.motd.raw);
  }
}

This lets users load any server's MOTD as a starting template. The server explorer on Minecraft ServerHub shows thousands of servers with their MOTDs if you need inspiration.

Adding the Minecraft Font

For an authentic look, use the Minecraft font. Add to your index.css:

@font-face {
  font-family: "Minecraft";
  src: url("/fonts/minecraft.woff2") format("woff2");
}

.font-minecraft {
  font-family: "Minecraft", monospace;
}

Then apply font-minecraft to the preview component for pixel-perfect rendering.

Going Further

Here are some ways to extend the editor:

Gradient text support — Automatically generate color transitions between two selected colors
Template library — Pre-built MOTD templates for different server types
Character counter — Minecraft MOTDs have a max length of ~59 characters per line
Icon support — Some servers use Unicode symbols in their MOTDs
Live preview with actual server data — Fetch real server info via the status API and show your MOTD alongside actual player counts

The Minecraft ServerHub MOTD Creator implements all of these features. You can use it as a reference for building a production-quality editor, or use it directly to create MOTDs for your server.

How Real Servers Use MOTDs

Looking at popular servers on the Minecraft ServerHub statistics page, you'll notice patterns:

Hypixel uses bold gold text with event announcements
Mineplex uses multi-colored text with seasonal themes
Most servers use 2 lines with the server name on top and a tagline below

Browse the server explorer to see how different communities style their MOTDs.

Conclusion

Building a MOTD editor teaches you about custom text formatting, real-time previews, and the Minecraft protocol. The combination of React for state management and Tailwind CSS for styling makes the development process fast and enjoyable.

For a production-ready MOTD creator with all the bells and whistles, check out the Minecraft ServerHub tools. And if you're building tools that integrate with Minecraft servers, the developer API provides all the data you need.

Built with Minecraft ServerHub — free tools for the Minecraft community.

Embed Minecraft Server Status Badges on Any Website (HTML, Markdown, BBCode)

Draginox — Wed, 11 Mar 2026 15:40:54 +0000

Server owners and community managers often want to display their Minecraft server's live status on a website, forum post, or GitHub README. In this guide, I'll show you how to embed dynamic server status badges anywhere using Minecraft ServerHub.

What Are Server Status Badges?

Server status badges are small, auto-updating images that show whether your Minecraft server is online, how many players are connected, and what version it runs. They work like CI/CD badges on GitHub but for game servers.

Here's an example badge URL for Hypixel:

https://minecraft-serverhub.com/api/badge/play.hypixel.net

This returns an SVG image that updates in real-time. No JavaScript needed on the client side — it's just an image tag.

Available Badge Styles

The Badge Generator offers three visual styles:

Rounded (Default)

The rounded style has smooth corners and a modern look. It works well on light backgrounds and README files:

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=rounded

Flat

The flat style matches the popular shields.io aesthetic. Perfect for GitHub READMEs where you already use flat badges:

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=flat

Minecraft

The minecraft style uses the iconic Minecraft font and color scheme. Great for fan sites and server communities:

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=minecraft

Customization Options

Every badge URL accepts query parameters for customization:

Parameter	Values	Description
style	rounded, flat, minecraft	Visual style
label	Any text	Custom left-side label
players	true/false	Show player count
version	true/false	Show server version
dark	true/false	Dark theme variant

Example with all options:

https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=flat&players=true&version=true&dark=true&label=My%20Server

Embedding in HTML

For websites, use a simple image tag wrapped in a link:

<a href="https://minecraft-serverhub.com/server/play.hypixel.net">
  <img src="https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=rounded"
       alt="Server Status"
       loading="lazy" />
</a>

This creates a clickable badge that links to the full server status page with detailed information.

Auto-Refreshing Badge

If you want the badge to update without page refresh, add a small script:

<img id="server-badge"
     src="https://minecraft-serverhub.com/api/badge/mc.example.com?style=rounded" />

<script>
setInterval(function() {
  var img = document.getElementById("server-badge");
  img.src = img.src.split("&t=")[0] + "&t=" + Date.now();
}, 60000); // Refresh every 60 seconds
</script>

Embedding in Markdown (GitHub, GitLab, dev.to)

For README files and Markdown-based platforms:

[![Server Status](https://minecraft-serverhub.com/api/badge/play.hypixel.net?style=flat)](https://minecraft-serverhub.com/server/play.hypixel.net)

This renders as a clickable badge image in any Markdown renderer.

GitHub README Example

Add server status to your Minecraft plugin's README alongside your CI badges:

# My Minecraft Plugin

[![Build](https://img.shields.io/github/actions/workflow/status/user/repo/build.yml)]()
[![Server Status](https://minecraft-serverhub.com/api/badge/play.myserver.com?style=flat)](https://minecraft-serverhub.com/server/play.myserver.com)

A custom plugin for our community server.

Embedding in BBCode (Forums)

Many Minecraft communities use XenForo, phpBB, or other forum software. Use BBCode to embed badges:

[url=https://minecraft-serverhub.com/server/play.myserver.com]
[img]https://minecraft-serverhub.com/api/badge/play.myserver.com?style=minecraft[/img]
[/url]

The minecraft style looks especially good on forum signatures and server listing posts.

Using the npm Package

For programmatic badge generation, install the minecraft-server-badge package:

npm install minecraft-server-badge

const { badge, html, markdown, bbcode } = require("minecraft-server-badge");

// Get just the badge URL
const url = badge("play.hypixel.net", { style: "flat", players: true });

// Get ready-to-paste HTML
const htmlCode = html("play.hypixel.net", { style: "rounded" });

// Get ready-to-paste Markdown
const mdCode = markdown("play.hypixel.net", { style: "flat" });

// Get ready-to-paste BBCode
const bbCode = bbcode("play.hypixel.net", { style: "minecraft" });

This is useful when building tools that generate embed codes for server owners, like the interactive badge generator on Minecraft ServerHub.

Using the Visual Badge Generator

If you prefer a no-code approach, the Badge Generator tool provides:

Live preview as you configure options
One-click copy for HTML, Markdown, and BBCode
All style and customization options in a visual interface
Instant badge preview with your actual server data

Just enter your server address, pick a style, toggle the options you want, and copy the embed code.

Combining with the Status API

For more advanced integrations, combine badges with the full status API. The badge gives you a visual indicator, while the API gives you raw data for custom displays:

// Show badge + detailed stats below it
async function getServerInfo(address) {
  const response = await fetch("https://minecraft-serverhub.com/api/server/" + address);
  const data = await response.json();
  return {
    badgeUrl: "https://minecraft-serverhub.com/api/badge/" + address + "?style=flat",
    players: data.players,
    version: data.version,
    motd: data.motd
  };
}

Real-World Examples

Here are some ways the Minecraft community uses status badges:

Server listing websites — Show live status next to each server entry
Discord server info channels — Embed badges in channel topics
Forum signatures — Display your server status in every forum post
GitHub READMEs — Show server status alongside project badges
Personal websites — Add a "Join my server" widget with live status

Monitoring Multiple Servers

If you run a network with multiple servers, you can display badges for each one. The server explorer shows how multiple servers can be displayed together with their status data.

Performance Considerations

The badge API is designed for embedding:

SVG format — Tiny file size, scales to any resolution
CDN-cached — Served through Cloudflare for fast global delivery
5-minute cache — Balances freshness with performance
No JavaScript required — Works as a plain image tag

Conclusion

Server status badges are the easiest way to show live Minecraft server information anywhere on the web. Whether you embed them in HTML, Markdown, or BBCode, they just work — no API keys, no JavaScript, no setup.

Try the Badge Generator to create your first badge, or explore the full developer documentation for advanced integrations.

Built with Minecraft ServerHub — free Minecraft server monitoring and status tools.

How to Build a Minecraft Server Discord Bot with Real-Time Status Updates

Draginox — Wed, 11 Mar 2026 15:38:37 +0000

Every Minecraft community wants to know: is the server online? How many players are on right now? In this tutorial, I'll show you how to build a Discord bot that posts live Minecraft server status updates using the Minecraft ServerHub API.

Why a Discord Bot?

Discord is where most Minecraft communities live. Instead of making players visit a website or use third-party tools, you can bring server status directly into your Discord channels. The bot will:

Show online/offline status with player counts
Update automatically every 5 minutes
Display the server MOTD and version info
Support both Java and Bedrock servers

We'll use the free Minecraft ServerHub REST API which requires no API key and returns JSON data for any server.

Prerequisites

Node.js 18+ installed
A Discord bot token (Discord Developer Portal)
A Minecraft server address to monitor

Project Setup

Create a new project and install dependencies:

mkdir mc-discord-bot && cd mc-discord-bot
npm init -y
npm install discord.js node-cron

Step 1: Create the API Helper

First, let's create a module that queries the server status API. The endpoint returns everything we need: player count, MOTD, version, latency, and the server icon.

// api.js
const BASE = "https://minecraft-serverhub.com/api/server";

async function getServerStatus(address) {
  const res = await fetch(BASE + "/" + address);
  if (!res.ok) throw new Error("API returned " + res.status);
  return res.json();
}

module.exports = { getServerStatus };

The API response includes fields like online, players.online, players.max, motd.clean, version, and latency. Check the full API documentation for all available fields.

Step 2: Build the Discord Embed

Discord embeds are the best way to display rich server information. We'll create a function that turns API data into a beautiful embed:

// embed.js
const { EmbedBuilder } = require("discord.js");

function createStatusEmbed(server, address) {
  if (!server.online) {
    return new EmbedBuilder()
      .setTitle("Server Status: " + address)
      .setColor(0xff0000)
      .setDescription("Server is **OFFLINE**")
      .setTimestamp();
  }

  const embed = new EmbedBuilder()
    .setTitle("Server Status: " + address)
    .setColor(0x00ff00)
    .addFields(
      { name: "Status", value: "Online", inline: true },
      { name: "Players", value: server.players.online + "/" + server.players.max, inline: true },
      { name: "Version", value: server.version || "Unknown", inline: true },
      { name: "Latency", value: server.latency + "ms", inline: true }
    )
    .setTimestamp()
    .setFooter({ text: "Powered by Minecraft ServerHub" });

  if (server.motd && server.motd.clean) {
    embed.setDescription(server.motd.clean);
  }

  if (server.icon) {
    embed.setThumbnail("data:image/png;base64," + server.icon);
  }

  return embed;
}

module.exports = { createStatusEmbed };

Step 3: Wire Up the Bot

Now let's create the main bot file that connects to Discord, registers a slash command, and sets up auto-updating:

// bot.js
const { Client, GatewayIntentBits, SlashCommandBuilder, REST, Routes } = require("discord.js");
const cron = require("node-cron");
const { getServerStatus } = require("./api");
const { createStatusEmbed } = require("./embed");

const TOKEN = process.env.DISCORD_TOKEN;
const CLIENT_ID = process.env.CLIENT_ID;

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

// Store channels that want auto-updates
const watchList = new Map();

client.on("ready", () => {
  console.log("Bot is online as " + client.user.tag);

  // Auto-update every 5 minutes
  cron.schedule("*/5 * * * *", async () => {
    for (const [channelId, config] of watchList) {
      try {
        const data = await getServerStatus(config.address);
        const embed = createStatusEmbed(data, config.address);
        const channel = await client.channels.fetch(channelId);
        if (config.messageId) {
          const msg = await channel.messages.fetch(config.messageId);
          await msg.edit({ embeds: [embed] });
        }
      } catch (err) {
        console.error("Update failed for " + channelId, err.message);
      }
    }
  });
});

Step 4: Add Slash Commands

// Add to bot.js
client.on("interactionCreate", async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === "status") {
    const address = interaction.options.getString("server");
    await interaction.deferReply();
    try {
      const data = await getServerStatus(address);
      const embed = createStatusEmbed(data, address);
      await interaction.editReply({ embeds: [embed] });
    } catch (err) {
      await interaction.editReply("Failed to check server: " + err.message);
    }
  }

  if (interaction.commandName === "watch") {
    const address = interaction.options.getString("server");
    await interaction.deferReply();
    try {
      const data = await getServerStatus(address);
      const embed = createStatusEmbed(data, address);
      const msg = await interaction.editReply({ embeds: [embed] });
      watchList.set(interaction.channelId, {
        address,
        messageId: msg.id,
      });
      await interaction.followUp("Now watching **" + address + "** in this channel. Updates every 5 minutes.");
    } catch (err) {
      await interaction.editReply("Failed: " + err.message);
    }
  }
});

client.login(TOKEN);

Step 5: Register Commands with Discord

Create a deployment script:

// deploy-commands.js
const { SlashCommandBuilder, REST, Routes } = require("discord.js");

const commands = [
  new SlashCommandBuilder()
    .setName("status")
    .setDescription("Check a Minecraft server status")
    .addStringOption(opt =>
      opt.setName("server").setDescription("Server address (e.g. play.hypixel.net)").setRequired(true)
    ),
  new SlashCommandBuilder()
    .setName("watch")
    .setDescription("Watch a server with auto-updates every 5 min")
    .addStringOption(opt =>
      opt.setName("server").setDescription("Server address").setRequired(true)
    ),
].map(cmd => cmd.toJSON());

const rest = new REST({ version: "10" }).setToken(process.env.DISCORD_TOKEN);

rest.put(Routes.applicationCommands(process.env.CLIENT_ID), { body: commands })
  .then(() => console.log("Commands registered"))
  .catch(console.error);

Running the Bot

export DISCORD_TOKEN="your-bot-token"
export CLIENT_ID="your-client-id"
node deploy-commands.js
node bot.js

Your bot is now live. Type /status play.hypixel.net in any channel to test it.

Adding Server Badges

Want to show your server status on your website too? Use the Minecraft ServerHub Badge Generator to create embeddable status badges. You can also install the minecraft-server-badge npm package for programmatic badge generation.

Exploring Live Data

If you want to see how different servers compare, check out the live statistics dashboard which tracks player counts across 5000+ servers. The server explorer lets you browse and search servers by gamemode, version, and region.

What's Next?

Some ideas to extend this bot:

Player join/leave notifications using the player list endpoint
Historical graphs by storing player counts over time
Multi-server support with a database backend
Web dashboard using Express.js and the Minecraft ServerHub API

Conclusion

Building a Discord bot for Minecraft server monitoring is straightforward with the right API. The Minecraft ServerHub platform provides free, reliable server data that you can integrate into any application — from Discord bots to web dashboards to mobile apps.

The full source code is available on GitHub. If you found this useful, check out my other tutorials on building with the Minecraft ServerHub developer tools.

Built with Minecraft ServerHub — the free Minecraft server monitoring platform.

Build a Minecraft Server Monitoring Dashboard with Node.js

Draginox — Wed, 11 Mar 2026 14:25:25 +0000

Ever wanted to build a real-time dashboard that monitors multiple Minecraft servers at once? In this tutorial, we'll build one using Node.js, Express, and the free Minecraft ServerHub API.

What We're Building

A web dashboard that:

Monitors multiple Minecraft servers simultaneously
Shows real-time player counts, version info, and MOTD
Auto-refreshes every 30 seconds
Displays server status with color-coded indicators

Prerequisites

Node.js 18+
Basic JavaScript/HTML knowledge
A list of Minecraft server IPs to monitor

Step 1: Project Setup

mkdir mc-dashboard && cd mc-dashboard
npm init -y
npm install express

Step 2: Create the API Client

The Minecraft ServerHub API provides free endpoints to query any Java or Bedrock server. No API key required.

Create api.js:

const SERVERS = [
  'play.hypixel.net',
  'mc.hypixel.net',
  '2b2t.org',
  'play.cubecraft.net'
];

async function fetchServerStatus(address) {
  const url = 'https://minecraft-serverhub.com/api/server/java/' + address;
  const res = await fetch(url);
  if (!res.ok) return { address, online: false };
  const data = await res.json();
  return {
    address,
    online: data.online,
    players: data.players || { online: 0, max: 0 },
    version: data.version?.name || 'Unknown',
    motd: data.motd?.clean || '',
    icon: data.icon || null
  };
}

async function fetchAllServers() {
  return Promise.all(SERVERS.map(fetchServerStatus));
}

module.exports = { fetchAllServers, SERVERS };

Step 3: Build the Express Server

Create server.js:

const express = require('express');
const { fetchAllServers } = require('./api');
const app = express();

app.get('/api/status', async (req, res) => {
  const servers = await fetchAllServers();
  res.json(servers);
});

app.get('/', (req, res) => {
  res.sendFile(__dirname + '/index.html');
});

app.listen(3000, () => {
  console.log('Dashboard running at http://localhost:3000');
});

Step 4: Create the Dashboard UI

Create index.html with a clean, dark-themed design. The dashboard fetches data from our Express API endpoint and renders a card for each server. Each card shows the server address, player count, version, and MOTD with a green/red border indicating online/offline status.

The frontend uses vanilla JavaScript with fetch() to poll our /api/status endpoint every 30 seconds, keeping the dashboard always up to date.

Step 5: Add Status Badges

Want to embed server status on your website or forum? Use the minecraft-server-badge npm package:

npm install minecraft-server-badge

const { badge, html } = require('minecraft-server-badge');

// Generate a status badge URL
const badgeUrl = badge('play.hypixel.net', { style: 'rounded' });

// Or get ready-to-use HTML embed code
const embed = html('play.hypixel.net', { dark: true });

You can also generate badges visually with the Badge Generator — no code needed.

Step 6: Run It

node server.js

Open http://localhost:3000 and you'll see your live dashboard monitoring all configured servers.

Going Further

Some ideas to extend the dashboard:

Historical data: Store player counts in a database and graph trends over time
Alerts: Send Discord webhooks when a server goes offline
Bedrock support: The API also supports Bedrock servers at /api/server/bedrock/address
Statistics: Check out live Minecraft ecosystem stats for global player trends

Resources

Minecraft ServerHub — Free server monitoring platform
API Documentation — Full REST API reference
minecraft-server-badge on npm — Embeddable status badges
Source code on GitHub — Open-source badge generator

Built with the free Minecraft ServerHub API. No API key required, no rate limits for reasonable use.

Free Minecraft Server Status API: Build Dashboards, Bots, and Widgets

Draginox — Wed, 11 Mar 2026 13:03:19 +0000

If you run a Minecraft server or build tools for the Minecraft community, you've probably needed real-time server status data: is the server online? How many players are connected? What version is it running?

I built a free API that answers these questions for any Minecraft server — and it powers Minecraft ServerHub, which monitors 5000+ servers. Here's how to use it.

The Badge API: Instant Status Widgets

The simplest way to show your server's status is an embeddable SVG badge. No API key needed, no JavaScript required:

<img src="https://minecraft-serverhub.com/api/badge/play.hypixel.net" alt="Server Status" />

This renders a live badge showing online/offline status and player count. It updates automatically — just drop the <img> tag on your website.

Customization Options

Parameter	Values	Default
`style`	`rounded`, `flat`, `minecraft`	`rounded`
`label`	Any text	Server IP
`players`	`true`, `false`	`true`
`version`	`true`, `false`	`false`
`dark`	`true`, `false`	`false`

Examples:

# Flat style with custom label
/api/badge/play.example.com?style=flat&label=My%20Server

# Dark mode with version info
/api/badge/play.example.com?dark=true&version=true

# Minimal — just online/offline
/api/badge/play.example.com?players=false

You can generate badges interactively with the badge generator tool — it gives you copy-paste HTML, Markdown, and BBCode.

Embedding on Different Platforms

HTML (websites):

<a href="https://minecraft-serverhub.com/servers?q=play.example.com">
  <img src="https://minecraft-serverhub.com/api/badge/play.example.com"
       alt="Server Status" />
</a>

Markdown (GitHub README, Discord):

[![Server Status](https://minecraft-serverhub.com/api/badge/play.example.com)](https://minecraft-serverhub.com)

BBCode (Minecraft forums, SpigotMC):

[url=https://minecraft-serverhub.com][img]https://minecraft-serverhub.com/api/badge/play.example.com[/img][/url]

How the Badge API Works Internally

The badge endpoint generates an SVG on the fly. Here's the simplified flow:

export async function GET(request: NextRequest, { params }) {
  const { address } = await params;
  const style = url.searchParams.get("style") || "rounded";

  // Look up server in database
  const server = await prisma.server.findFirst({
    where: {
      OR: [
        { ipAddress: address },
        { slug: address },
      ],
      status: { in: ["ACTIVE", "PENDING"] },
    },
    select: {
      name: true,
      isOnline: true,
      playersOnline: true,
      maxPlayers: true,
      version: true,
    },
  });

  // Generate dynamic SVG
  const svg = generateBadgeSVG({ server, style, address });

  return new NextResponse(svg, {
    headers: {
      "Content-Type": "image/svg+xml",
      "Cache-Control": "public, s-maxage=120, stale-while-revalidate=300",
      "Access-Control-Allow-Origin": "*",
    },
  });
}

Key design decisions:

SVG, not PNG — SVG is vector-based, looks crisp at any size, and is tiny (~1KB vs 5KB+ for PNG).
CORS wildcard — Access-Control-Allow-Origin: * lets anyone embed it.
2-minute cache — s-maxage=120 with stale-while-revalidate=300 keeps CDN load low while data stays reasonably fresh.

The SVG generation uses shields.io-style badges. The left side shows the server name/IP, and the right side shows the status with a green (online) or red (offline) background.

Building a Discord Bot with the API

Here's a quick Discord bot that checks server status on command:

const { Client, GatewayIntentBits, EmbedBuilder } = require("discord.js");

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});

client.on("interactionCreate", async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === "status") {
    const address = interaction.options.getString("server");

    // Fetch from the API
    const res = await fetch(
      `https://minecraft-serverhub.com/api/servers/search?q=${encodeURIComponent(address)}`
    );
    const data = await res.json();
    const server = data.servers?.[0];

    if (!server) {
      return interaction.reply("Server not found in our database.");
    }

    const embed = new EmbedBuilder()
      .setTitle(server.name)
      .setColor(server.isOnline ? 0x22c55e : 0xef4444)
      .addFields(
        { name: "Status", value: server.isOnline ? "Online" : "Offline", inline: true },
        { name: "Players", value: `${server.playersOnline}/${server.maxPlayers}`, inline: true },
        { name: "Version", value: server.version || "Unknown", inline: true }
      )
      .setFooter({ text: "Data from minecraft-serverhub.com" });

    return interaction.reply({ embeds: [embed] });
  }
});

Building a Server Status Page

Many server owners want a status page on their own website. Here's a React component:

import { useState, useEffect } from "react";

function ServerStatus({ address }: { address: string }) {
  const [server, setServer] = useState(null);

  useEffect(() => {
    const fetchStatus = async () => {
      const res = await fetch(
        `https://minecraft-serverhub.com/api/servers/search?q=${address}`
      );
      const data = await res.json();
      setServer(data.servers?.[0] ?? null);
    };

    fetchStatus();
    const interval = setInterval(fetchStatus, 60000); // Refresh every minute
    return () => clearInterval(interval);
  }, [address]);

  if (!server) return <div>Loading...</div>;

  return (
    <div style={{
      display: "flex",
      alignItems: "center",
      gap: "8px",
      padding: "12px",
      borderRadius: "8px",
      background: server.isOnline ? "#f0fdf4" : "#fef2f2",
    }}>
      <div style={{
        width: 12,
        height: 12,
        borderRadius: "50%",
        background: server.isOnline ? "#22c55e" : "#ef4444",
      }} />
      <span>{server.name}</span>
      <span style={{ marginLeft: "auto", fontWeight: "bold" }}>
        {server.playersOnline}/{server.maxPlayers} players
      </span>
    </div>
  );
}

Or even simpler — just use the badge:

<!-- Zero JavaScript, auto-updates -->
<img src="https://minecraft-serverhub.com/api/badge/play.example.com?style=flat"
     alt="Server Status"
     style="height: 20px;" />

Rate Limits and Fair Use

The API is free with reasonable limits:

Badge API: No hard limit, CDN cached for 2 minutes
Search API: Rate limited per IP (reasonable use)
No API key required for read-only badge endpoints

If you need higher limits or want server data in bulk, check the ServerHub statistics page for aggregate data.

Use Cases I've Seen

Since launching the API, people have built:

Discord bots that post hourly server status updates
Forum signatures with live player counts
Twitch stream overlays showing the server they're playing on
Server websites with embedded status badges
Monitoring dashboards tracking multiple servers

The badge alone gets embedded on hundreds of server websites, which is great for the Minecraft community — everyone can see at a glance if a server is up.

Getting Started

Quick badge: Replace play.example.com with your server IP:

   https://minecraft-serverhub.com/api/badge/play.example.com

Customize it: Use the interactive badge generator
Build with it: Hit the search API for structured data:

   https://minecraft-serverhub.com/api/servers/search?q=play.example.com

Track your server: Add it to ServerHub for free monitoring, voting, and analytics.

The entire platform is free. No sign-up needed for badges, no API key for basic status checks. If you run a Minecraft server, there's no reason not to have a live status badge on your website.

Questions? Found a bug? Open an issue or reach out. And if you build something cool with the API, I'd love to see it.

How We Index 5000+ Minecraft Servers: Database Design and Search Architecture

Draginox — Wed, 11 Mar 2026 12:36:23 +0000

When you're building a platform that indexes thousands of game servers with real-time data, your database design makes or breaks you. A bad schema means slow queries, missing data, and frustrated users. A good one scales effortlessly.

Here's how I designed the database behind Minecraft ServerHub, a server discovery platform that tracks 5000+ servers with live player counts, uptime history, and community voting.

The Core Problem

A Minecraft server listing needs to:

Store server metadata (name, IP, port, version, description)
Track real-time status (online/offline, player count, latency)
Calculate uptime from historical pings
Support voting, reviews, and rankings
Handle search with filters (gamemode, version, country, player count)
Aggregate statistics across the entire ecosystem

All of this needs to feel fast — sub-200ms response times for listing pages.

Schema Design: The Server Model

The Server model is the core of everything. Here's the simplified version:

model Server {
  id             String       -- pk -- primary-key, cuid()
  name           String
  slug           String       -- unique
  ipAddress      String
  port           Int          -- default(25565)
  edition        String       -- default("java")

  // Status fields updated by ping system
  isOnline       Boolean      -- default(false)
  playersOnline  Int          -- default(0)
  maxPlayers     Int          -- default(0)
  version        String?
  software       String?
  uptime         Float        -- default(0)
  latency        Int?

  // Ranking signals
  votesThisMonth Int          -- default(0)
  totalClicks    Int          -- default(0)
  uniqueVisitors Int          -- default(0)

  // Lifecycle
  status         ServerStatus -- default(PENDING)
  tier           ServerTier   -- default(FREE)

  // Relations
  pingHistory    PingHistory[]
  reviews        Review[]
  votes          Vote[]
  tags           ServerTag[]

  @-- index([status, votesThisMonth])
  @-- index([status, country])
  @-- index([status, createdAt])
}

Why These Indexes?

The three composite indexes cover our most common query patterns:

[status, votesThisMonth] — The default server listing sorted by votes. This is the homepage query.
[status, country] — Country-specific pages like /servers/country/us. We have 30+ country landing pages.
[status, createdAt] — "Recently added" sorting.

Every query filters by status = ACTIVE first, which is why status is always the first field in the composite index.

The Dual-Table Strategy

We have two server tables: Server (user-submitted, with ownership) and SeedServer (pre-populated from discovery crawlers).

Why two tables instead of a source field on one table?

Different data models — Server has ownership, verification, premium tiers, votes. SeedServer is just raw data.
Query isolation — Listing queries only hit Server. Search hits both with UNION.
No contamination — Seed data never appears in rankings until a user claims and verifies it.

Search across both tables:

async function searchServers(query: string) {
  const [servers, seedServers] = await Promise.all([
    prisma.server.findMany({
      where: {
        status: "ACTIVE",
        OR: [
          { name: { contains: query, mode: "insensitive" } },
          { ipAddress: { contains: query } },
        ],
      },
      take: 20,
      orderBy: { votesThisMonth: "desc" },
    }),
    prisma.seedServer.findMany({
      where: {
        OR: [
          { name: { contains: query, mode: "insensitive" } },
          { ipAddress: { contains: query } },
        ],
      },
      take: 10,
    }),
  ]);

  return [...servers, ...seedServers.filter(
    (seed) => !servers.some((s) => s.ipAddress === seed.ipAddress)
  )];
}

Ping History: Time-Series Without TimescaleDB

We track every ping in a PingHistory table. With 5000 servers pinged every 5 minutes, that's ~1.4 million rows per day.

model PingHistory {
  id        String   -- pk -- primary-key, cuid()
  serverId  String
  isOnline  Boolean
  players   Int      -- default(0)
  latency   Int?
  createdAt DateTime -- auto-timestamp

  server    Server   -- relation(fields: [serverId], references: [id])

  @-- index([serverId, createdAt])
}

The composite index on [serverId, createdAt] is essential. Without it, calculating uptime for a single server would scan millions of rows.

For uptime, we use groupBy instead of loading all rows:

const pings = await prisma.pingHistory.groupBy({
  by: ["isOnline"],
  where: {
    serverId,
    createdAt: { gte: thirtyDaysAgo },
  },
  _count: true,
});

This returns just 2 rows (online count and offline count) regardless of how many pings exist. PostgreSQL handles the aggregation.

The Voting System: Preventing Abuse

Votes determine server ranking, so they're a target for manipulation:

model Vote {
  id                String   -- pk -- primary-key, cuid()
  serverId          String
  ipHash            String   // SHA256 of IP — no raw IPs stored
  minecraftUsername String?
  fingerprint       String?
  votedAt           DateTime -- auto-timestamp

  @-- unique([serverId, ipHash, votedAt])
  @-- index([serverId, votedAt])
}

Key design decisions:

IP hashing — We never store raw IP addresses. SHA256 hash is enough for deduplication.
Composite unique constraint — One vote per IP per server per day.
Fingerprinting — Browser fingerprint catches multi-account voting.
Votifier integration — Servers can verify votes and reward players.

Aggregated Statistics

The statistics page shows ecosystem-wide data. We pre-aggregate this instead of computing it live:

const [
  totalServers,
  onlineServers,
  totalPlayers,
  gamemodeDistribution,
  versionDistribution,
] = await Promise.all([
  prisma.server.count({ where: { status: "ACTIVE" } }),
  prisma.server.count({ where: { status: "ACTIVE", isOnline: true } }),
  prisma.server.aggregate({ where: { status: "ACTIVE" }, _sum: { playersOnline: true } }),
  prisma.serverTag.groupBy({ by: ["tagId"], _count: true }),
  prisma.server.groupBy({ by: ["version"], _count: true, where: { status: "ACTIVE" } }),
]);

With Redis caching at a 5-minute TTL, the statistics page loads in under 100ms.

Lessons Learned

1. Composite indexes are not optional at scale. Our most important optimization was adding @-- index([status, votesThisMonth]). Before that, the homepage query took 800ms. After: 12ms.

2. Two tables > one table with a type field. The Server/SeedServer split keeps queries clean and prevents accidental mixing of verified and unverified data.

3. Aggregate, don't scan. Using groupBy for uptime calculation instead of loading all ping records reduced memory usage by 100x.

4. Hash sensitive data at write time. Storing IP hashes instead of raw IPs means a database breach doesn't expose user locations.

5. Pre-compute expensive stats. The statistics page runs 18 queries, but they're all served from cache 99% of the time.

The Numbers

The full schema has 70+ models covering servers, users, analytics, payments, and moderation. At peak:

5000+ servers indexed
170,000+ players tracked
~1.4M ping records/day
< 200ms p95 response time
PostgreSQL handling it all on a single instance

You can see the live data on the Minecraft ServerHub statistics dashboard.

Building something similar? The key is starting with the right indexes. Profile your top 5 queries, add composite indexes for each, and cache aggressively. Your database will thank you.

Building a Real-Time Minecraft Server Monitor with Next.js

Draginox — Wed, 11 Mar 2026 12:31:04 +0000

Every day, millions of Minecraft players search for multiplayer servers. But finding one that's actually online, has players, and runs the right version? That's surprisingly hard.

I built Minecraft ServerHub to solve this. It pings 5000+ servers every 5 minutes and shows real-time player counts, uptime history, and version info. Here's how the monitoring system works under the hood.

The Architecture

The stack:

Next.js 14 (App Router) for the frontend and API routes
PostgreSQL with Prisma ORM for persistent storage
Redis for caching and rate limiting
minecraft-server-util for direct server pings

The key insight: instead of relying on third-party APIs (which have rate limits), we ping Minecraft servers directly using the Minecraft protocol.

Direct Server Pinging

Minecraft servers speak a well-defined protocol. When you connect to a server, the first thing that happens is a "status" handshake that returns the server's MOTD, player count, version, and favicon.

We use the minecraft-server-util library to handle this:

import { status, statusBedrock } from "minecraft-server-util";

async function pingServer(ip: string, port: number, edition: "java" | "bedrock") {
  const timeout = 5000; // 5 second timeout

  if (edition === "bedrock") {
    const response = await statusBedrock(ip, port, { timeout });
    return {
      online: true,
      players: response.players.online,
      maxPlayers: response.players.max,
      version: response.version.name,
      motd: response.motd.clean,
    };
  }

  const response = await status(ip, port, { timeout });
  return {
    online: true,
    players: response.players.online,
    maxPlayers: response.players.max,
    version: response.version.name,
    motd: response.motd.clean,
    favicon: response.favicon ?? null,
  };
}

This gives us zero API rate limits. The only constraint is network throughput.

Batch Processing at Scale

Pinging 5000 servers sequentially would take forever. So we batch them with controlled concurrency:

const BATCH_SIZE = 400;
const CONCURRENT_PINGS = 15;

async function processBatch(servers: Server[]) {
  const results = [];

  for (let i = 0; i < servers.length; i += CONCURRENT_PINGS) {
    const chunk = servers.slice(i, i + CONCURRENT_PINGS);
    const chunkResults = await Promise.allSettled(
      chunk.map((server) =>
        pingServer(server.ipAddress, server.port, server.edition)
      )
    );
    results.push(...chunkResults);
  }

  return results;
}

Why Promise.allSettled instead of Promise.all? Because servers go offline. We don't want one timeout to kill the entire batch.

With 15 concurrent connections and a 5-second timeout, worst case we process 15 servers every 5 seconds. That's 180 servers per minute — enough to cover our entire database in under 30 minutes, well within our 5-minute ping cycle when spread across cron invocations.

Multi-Layer Caching with Redis

Every ping result is cached to avoid hitting the database on every page load:

const CACHE_TTLS = {
  SERVER_LIST: 300,      // 5 minutes
  SERVER_DETAIL: 300,    // 5 minutes
  SERVER_PING: 360,      // 6 minutes (slightly longer than ping interval)
  TAGS: 3600,            // 1 hour
  GLOBAL_STATS: 86400,   // 1 day
};

async function getCachedServer(id: string) {
  const cacheKey = `server:${id}`;

  // Try Redis first
  const cached = await redis.get(cacheKey);
  if (cached) return JSON.parse(cached);

  // Fall back to database
  const server = await prisma.server.findUnique({ where: { id } });

  // Cache for next request
  if (server) {
    await redis.setex(cacheKey, CACHE_TTLS.SERVER_DETAIL, JSON.stringify(server));
  }

  return server;
}

We also have an in-memory fallback cache for when Redis is unavailable. It uses a stale-while-revalidate pattern with 2x TTL:

class MemoryCache {
  private cache = new Map<string, { data: any; expires: number; stale: number }>();

  get(key: string) {
    const entry = this.cache.get(key);
    if (!entry) return null;

    if (Date.now() < entry.expires) return entry.data; // Fresh
    if (Date.now() < entry.stale) return entry.data;   // Stale but usable

    this.cache.delete(key);
    return null;
  }
}

Storing Ping History for Uptime Calculation

Every ping creates a PingHistory record:

model PingHistory {
  id        String   @id @default(cuid())
  serverId  String
  isOnline  Boolean
  players   Int      @default(0)
  latency   Int?     // round-trip ms
  createdAt DateTime @default(now())

  server    Server   @relation(fields: [serverId], references: [id])

  @@index([serverId, createdAt]) // Composite index for uptime queries
}

Uptime is calculated from a 30-day rolling window:

async function calculateUptime(serverId: string): Promise<number> {
  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

  const pings = await prisma.pingHistory.groupBy({
    by: ["isOnline"],
    where: {
      serverId,
      createdAt: { gte: thirtyDaysAgo },
    },
    _count: true,
  });

  const online = pings.find((p) => p.isOnline)?._count ?? 0;
  const total = pings.reduce((sum, p) => sum + p._count, 0);

  return total > 0 ? Math.round((online / total) * 10000) / 100 : 0;
}

The composite index on [serverId, createdAt] is critical — without it, this query would do a full table scan on millions of rows.

The Cron Setup

We use Next.js API routes as cron endpoints, authenticated with a secret:

// /api/cron/ping-servers/route.ts
export async function GET(request: NextRequest) {
  const authHeader = request.headers.get("authorization");
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const servers = await getNextBatch(); // Gets servers not pinged recently
  const results = await processBatch(servers);
  await savePingResults(results);

  return NextResponse.json({
    processed: results.length,
    online: results.filter(r => r.status === "fulfilled").length,
  });
}

An external cron service (we use cron-job.org) calls this endpoint every 5 minutes. The batch system ensures each invocation processes a different set of servers.

Embeddable Status Badges

One feature that turned out to be really popular: embeddable SVG badges that server owners put on their websites.

https://minecraft-serverhub.com/api/badge/play.example.com?style=rounded&players=true

This returns a dynamic SVG that shows online/offline status and player count. The SVG is regenerated on each request with a 2-minute cache. Server owners embed it on their websites, forums, and Discord — and each badge links back to the server's page on ServerHub.

Results

After 3 months of running this system:

5000+ servers monitored across Java and Bedrock editions
170,000+ players tracked simultaneously at peak
99.7% uptime on the monitoring system itself
< 200ms average response time thanks to Redis caching

The full platform is live at minecraft-serverhub.com with a live statistics dashboard showing real-time ecosystem data.

Key Takeaways

Direct protocol access beats APIs — no rate limits, faster, more reliable
Batch with concurrency control — Promise.allSettled with chunking handles failures gracefully
Multi-layer caching is essential — Redis + in-memory prevents cascade failures
Composite indexes matter — a missing index on ping history turned a 2-second query into 200ms
SVG badges are link magnets — server owners embed them everywhere

If you're building any kind of monitoring system, the pattern of "direct protocol ping → batch process → cache aggressively → serve from cache" scales surprisingly well with minimal infrastructure.

Check out the server badge generator if you run a Minecraft server — it's free and takes 30 seconds to set up.

How I Built a Real-Time Minecraft Server Status Checker with Next.js 15 and Server-Sent Events

Draginox — Fri, 06 Mar 2026 23:53:59 +0000

I needed to build a real-time Minecraft server status checker for Minecraft ServerHub — a server list with 1,000+ servers. The naive approach (polling an API every few seconds) felt wasteful. So I went with Server-Sent Events (SSE) to stream results back to the client as soon as they arrive.

Here's exactly how it works, including the raw TCP protocol implementation.

The Minecraft Server List Ping Protocol

Minecraft Java servers use a custom binary TCP protocol for status pings. You have to:

Open a raw TCP socket to port 25565
Send a Handshake packet (packet ID 0x00) to set up the connection
Send a Status Request packet (packet ID 0x00 again, but in the Status state)
Read the Status Response — a JSON payload with player count, version, MOTD, etc.

The binary format uses variable-length integers (VarInts) — each byte uses 7 bits for data and 1 bit to indicate if more bytes follow.

The SSE API Route (Next.js 15 App Router)

Instead of blocking until we have a result, the API route opens the TCP connection and streams events back as soon as data arrives. This means the UI can show "connecting…" → "checking…" → result in near real-time.

// app/api/ping/route.ts
export const runtime = "nodejs"; // required for raw TCP sockets

export async function GET(req: NextRequest) {
  const host = new URL(req.url).searchParams.get("host") ?? "";
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      const send = (event: string, data: unknown) => {
        controller.enqueue(
          encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
        );
      };
      try {
        send("status", { stage: "connecting" });
        const result = await pingJavaServer(host);
        send("result", result);
      } catch (err) {
        send("error", { online: false, message: err instanceof Error ? err.message : "Unreachable" });
      } finally {
        controller.close();
      }
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
    },
  });
}

Why SSE Instead of WebSockets?

SSE is unidirectional (server → client only) — perfect for "fire a query, stream the result"
No special server needed — works over standard HTTP, no WebSocket upgrade handshake
Built-in reconnect — browsers auto-reconnect if the connection drops
Simpler auth — cookies and headers work the same as regular HTTP requests

The Live Tool

You can try the finished tool at minecraft-serverhub.com/tools/server-status-checker — it checks any Java or Bedrock server in real time and shows the MOTD with formatting.

The full API documentation is also available if you want to build your own integration (no API key required, completely free).

If you have questions about the Minecraft ping protocol or the SSE implementation, drop them in the comments. Happy coding!