Minecraft ServerHub API

Free Minecraft server ping API with no key: online state, player counts, version, MOTD and the server icon as a data URI, plus SVG and PNG status badges. Live example.

No API key requiredHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the Minecraft ServerHub API?

Minecraft ServerHub is a free API that pings any Java or Bedrock Minecraft server and returns whether it is online, its current and maximum player counts, its version string, its MOTD and its icon as a base64 data URI. It also renders live status badges as SVG or PNG.

What ServerHub adds beyond a plain ping is presentation. The same host that answers `/api/ping` with JSON also answers `/api/badges/{slug}/svg` with a rendered status badge and `/api/widgets/{slug}` with an embeddable panel, so a README, a forum signature and a website can all show live player counts without any of them running code. The badge endpoints get their own, higher rate allowance for exactly that reason.

Two fields in the JSON repay a closer look. `favicon` is a complete `data:image/png;base64,...` URI, so it drops straight into an image tag with no extra request and no cross-origin concern. `motd`, by contrast, arrives as the raw server string, newlines and Minecraft section-sign colour codes intact, so it needs stripping or translating before display. Note too that the allow-origin header names ServerHub's own domain rather than a wildcard, which means browser code on your site cannot call it directly.

Quick facts

Base URL: https://minecraft-serverhub.com/api
Authentication: No key or account for the public endpoints; the documentation states they are free for personal and commercial use.
Rate limit: 60 requests per minute per address for most endpoints, and 120 per minute for the badge endpoints, per the developer documentation.
Pricing: Free.
CORS: Not enabled — call it from your server
Official docs: Read the docs

How to use the Minecraft ServerHub API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Ping a Minecraft server for its live player count

GET https://minecraft-serverhub.com/api/ping?host=mc.hypixel.net&port=25565&platform=java

curl

curl 'https://minecraft-serverhub.com/api/ping?host=mc.hypixel.net&port=25565&platform=java'

JavaScript (fetch)

const res = await fetch("https://minecraft-serverhub.com/api/ping?host=mc.hypixel.net&port=25565&platform=java");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://minecraft-serverhub.com/api/ping?host=mc.hypixel.net&port=25565&platform=java", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "online": true,
  "players": {
    "online": 18501,
    "max": 200000,
    "sample": []
  },
  "version": "Requires MC 1.8 / 1.21",
  "motd": "                 Hypixel Network [1.8/26.2]\n   SB 0.27 TORRHUS & SAFARI | SUMMER EVENT",
  "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAt0UlEQVR4XnV7B3hc1bX12Oq9Te+9d400TV2yLFndkiXZlm1Z7r3gChibEhwgiQ1JSELCgzyaqYFQQggvCQ/SXx6QkBgMJCZAIGBiMMbdWv86d2Qbkvf7+/Z3PTOambvXWXvttc+9IzObAr/oGh47Om/VCrSNLMD6q67Dpj3XY8boIqT6hpHuH0GaR/H/i9E7B7G2bun4hef/j2icPYLGwamQ/j+KrrExjKxYgokNK7D8stVYtW0N1l6+FusuxjqsZ2wQccV6bLzy/x+X7dqALbs2Yuvujdi+ZwO2X73xYmzjc3tu3IW9+7+EG75+A3bfuBvX778BE5vWomds8VmHM/pbWcfA8Hs/fPrRczd8fR9PbAL1fTzJvjn8o61o6BtCbXsPoi2dCDe2I9QwA8H6NgTrWhFINSOQbpHCz/9LkWy6GL5k479EQyYSDfzbRgTTTQjViWhEuP7z0YBwHSNdj0i6ARG+ngnx/4bMc6kGRNONqOb7o4wwPz+czPy/ur6ZIY58zIg1tKC2qRW1LTMQSrWgiTntvvF6/PDpByf7Fiz8TNY9tnDyznv2o2fOMGy+JMz+JIy+BDw1TbAE0zAHUtJzpqkQr4mQHovjv4R56jN0DL34e3+Kf5sJC8Mq/Z/v9fJz3LUoUxqRlVWEabJ8Rh6m81iYVwWNwQWbtRpWYxgWYwgqlQ1ypRXllWYo1XYUlNggk8mmogQyhQN6fp7BHoPelYDOw+/3iGMCWreIuPR/JV9r75+Nfd/cjdXb1kLWPm8hKbcV/lg9KlROKNQWVKnMKC7XorzKgAq5ERUKIyoZVQyFwiRFuYKvXQy+prJArnWgVO9CudEDtyMCl7NaAtUokvUKgARoSWjsYRQVVSCXCWczgfIqJTRGG9QGK/RmF8JN7ZixZDlmTCxHPUumfnAuWhYsxsylK9G7Zh06lq/C4NqNWLRxC8Y3b8PImo0YXLYG3kQLqtRmflccRk8tAamGwVMDk7sGRld1ZpG4AIFkC/rHRjGxfjlkrcNj2Lz7SgRq61FUpoeqygJVhRmqSguUPKqlyDxnr7QhoPCgRuWHvtwAeakWhbnFKMovg7LSCk2VA3a5AzGlC8uNEYwZwqhT2VFUWIb84nLIcyuQN72Qq65FVlEZk7bD4g2jfs48tDO59mUrMZPJ9Wy8DF1rNqB53gRaFy1D26IVGNlzNVbt24e999yDZTfdhAPPPou3PvgAh9//B37y69/g0Sd/jNGlq+BlKeq5CMoSFUoK+J0lSihKVSgvVnIBTdC5YrC

Parameters

Parameter	Type	Required	Description
`host`	query	Required	Server hostname or IP address to ping. `mc.hypixel.net`
`port`	query	Optional	Server port. Defaults to the standard port for the platform. `25565`
`platform`	query	Optional	`java` or `bedrock`. Bedrock servers use a different ping protocol, so this matters. `java`
`style`	query	Optional	Badge style on the `/badges/{slug}/svg` and `/png` endpoints. `flat`
`theme / size`	query	Optional	Appearance controls for the embeddable widget endpoint. `dark`

Response fields

onlineboolean: Whether the ping succeeded. Check this first — an offline server still returns HTTP 200.
players.online / players.maxinteger: Current and maximum player counts as the server reports them. Large networks report figures in the tens of thousands.
players.samplearray: The sample player list, which most public servers disable. Expect an empty array rather than names.
versionstring: Free-text version string exactly as the server advertises it, for example `Requires MC 1.8 / 1.21` — not a parseable version number.
motdstring: Raw message of the day, containing literal newlines and Minecraft colour codes. Strip or translate before rendering.
faviconstring: The server icon as a complete `data:image/png;base64` URI, usable directly as an image source with no second request.

What you can build with the Minecraft ServerHub API

Show a live player count on a server's website or landing page
Embed a status badge in a GitHub README or forum signature
Alert a Discord channel when a server goes offline
Build a server list that pings dozens of hosts on a schedule
Display a server's icon and MOTD without connecting to it yourself

Common errors and how to fix them

online: false with HTTP 200

The server did not answer the ping — offline, firewalled, or a wrong port.

Fix: Branch on the `online` field, not the status code, and confirm the port matches the platform before reporting an outage.

Garbled MOTD text

The MOTD carries section-sign colour codes and newlines verbatim.

Fix: Strip the colour codes with a regular expression, or translate them into spans if you want the colours.

A CORS error in the browser

The allow-origin header names ServerHub's own domain, not a wildcard.

Fix: Call it from your backend and cache the result; pinging on every page load would exhaust the rate limit anyway.

429

Above 60 requests a minute.

Fix: Ping on a schedule and serve the cached result. Player counts change slowly enough that a minute of staleness is invisible.

Minecraft ServerHub API — frequently asked questions

Does the Minecraft ServerHub API need an API key?

No. The ping, badge and widget endpoints are all key-free, documented as free for personal and commercial use, and limited to 60 requests a minute — 120 for badges — per address.

Does it work with Bedrock servers?

Yes. Pass `platform=bedrock` and it uses the Bedrock ping protocol instead of the Java one. Getting this wrong is the usual reason a server that is clearly up comes back as offline.

How do I display the server icon?

The `favicon` field is already a full base64 data URI, so assign it straight to an image source. There is no second request to make and no cross-origin image to worry about.

Why is players.sample always empty?

Most public servers disable the sample player list in their configuration, so there is nothing for the ping to return. Treat a populated sample as a bonus rather than something to build a feature on.

Tools that pair with this API

Base64 to Image Converter

Convert a Base64 string back to an image online. Paste a data URL or raw Base64, preview instantly and download as PNG, JPG or the original format.

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

SVG to PNG Converter

Convert SVG vector files to PNG at any resolution you choose. Render crisp raster images from SVG in your browser — free, instant and private.

Minecraft ServerHub is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.