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
[](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
[](https://minecraft-serverhub.com/server/play.myserver.com)
Join us at `play.myserver.com` - A survival community with custom plugins!
## Tech Stack
Step 4: Add Multiple Server Badges
If you run a network with multiple servers, display them all:
## Our Server Network
| Server | Status |
|--------|--------|
| Hub | [](https://minecraft-serverhub.com/server/hub.mynetwork.com) |
| Survival | [](https://minecraft-serverhub.com/server/survival.mynetwork.com) |
| Creative | [](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
[](https://github.com/user/repo/actions)
[](https://github.com/user/repo/releases)
[](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);
// [](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.
Top comments (0)