Minecraft Server Status - JSON API

Welcome to the Minecraft Server Status JSON API. This API combines the Ping and Query protocols into one simple JSON output.

Advertising - Your banner here?

Please note: This page is for developers who wants to integrate the status of Minecraft servers. If you only need to check the status a server, please go to the main page here.
Please note: The API was bumped to version 2, version 1 will still work. Read below for the changes.
Please note: Too many requests pr. minute to the API will get you blocked, so moderate your number of request!

Using the API

Use the following endpoint to get the status of a server: https:/api.mcsrvstat.us/2/<address>

The data is retuned as application/json and is currently cached for 120 seconds.

If an address works in Minecraft, it works with this API. If you do not specify a port, the API will find it. SRV records are also supported.



//Get the status and decode the JSON
$status = json_decode(file_get_contents('https://api.mcsrvstat.us/2/domain.tld'));

//Show the version
echo $status->version;

//Show a list of players
foreach ($status->players->list as $player) {
	echo $player.'<br />';

JavaScript (jQuery)

//Get the status
$.getJSON('https://api.mcsrvstat.us/2/domain.tld', function(status) {
	//Show the version

	//Show a list of players
	$.each(status.players.list, function(index, player){

Response when server is Online

	"online": true,
	"ip": "",
	"port": 25567,
	"debug": { //See section below for information about the values
		"ping": true,
		"query": true,
		"srv": true,
		"querymismatch": false,
		"ipinsrv": false,
		"animatedmotd": false,
		"proxypipe": false,
		"cachetime": 1518553220
	"motd": {
		"raw": ["\u00a7cEver\u00a7r\u00a79PvP \u00a7r\u00a77- \u00a7r\u00a72\u00c9n server, for alle", "\u00a7r\u00a7fSe dine stats p\u00e5 \u00a7r\u00a76stats.everpvp.dk\u00a7r"],
		"clean": ["EverPvP - \u00c9n server, for alle", "Se dine stats p\u00e5 stats.everpvp.dk"],
		"html": ["<span style=\"color: #FF5555\">Ever<\/span><span style=\"color: #5555FF\">PvP <\/span><span style=\"color: #AAAAAA\">- <\/span><span style=\"color: #00AA00\">\u00c9n server, for alle<\/span>", "<span style=\"color: #FFFFFF\">Se dine stats p\u00e5 <\/span><span style=\"color: #FFAA00\">stats.everpvp.dk<\/span>"]
	"players": {
		"online": 2,
		"max": 100,
		"list": ["Spirit55555", "sarsum33"] //Only included when there are any players
	"version": "1.12", //Could include multiple versions or additional text
	"protocol": 332, //Only included when ping is used, see more here: http://wiki.vg/Protocol_version_numbers
	"hostname": "server.mymcserver.tld", //Only included when a hostname is detected
	"icon": "data:image\/png;base64,iVBORw0KGgoAAAANSUhEU...dSk6AAAAAElFTkSuQmCC", //Only included when an icon is detected
	"software": "BungeeCord", //Only included when software is detected
	"map": "MyMcWorld", //Only included when the value is not "world"
	"plugins": { //Only included when plugins are detected
		"names": ["WordEdit", "WorldGuard"],
		"raw": ["WordEdit 6.1.5", "WorldGuard 6.2"]
	"mods": { //Only included when mods are detected
		"names": ["BiomesOPlenty", "MoreFurnaces"],
		"raw": ["BiomesOPlenty 2.1.0", "MoreFurnaces 1.3.9"]
	"info": { //Only included when detecting that the player samples are used for information
		"raw": ["\u00a77\u00bb \u00a7cKitPvP \u00a77:: \u00a7f1 \u00a77online", "\u00a77\u00bb \u00a7bSurvivalGames \u00a77:: \u00a7f0 \u00a77online"],
		"clean": ["\u00bb KitPvP :: 1 online", "\u00bb SurvivalGames :: 0 online"],
		"html": ["<span style=\"color: #AAAAAA\">\u00bb <\/span><span style=\"color: #FF5555\">KitPvP <\/span><span style=\"color: #AAAAAA\">:: <\/span><span style=\"color: #FFFFFF\">1 <\/span><span style=\"color: #AAAAAA\">online<\/span>", "<span style=\"color: #AAAAAA\">\u00bb <\/span><span style=\"color: #55FFFF\">SurvivalGames <\/span><span style=\"color: #AAAAAA\">:: <\/span><span style=\"color: #FFFFFF\">0 <\/span><span style=\"color: #AAAAAA\">online<\/span>"]

Response when server is Offline

	"online": false,
	"ip": "", //Could be empty
	"port": 25567, //Could be empty
	"debug": { //See section below for information about the values
		"srv": true,
		"ipinsrv": false,
		"cachetime": 1518553220
	"hostname": "not-working.mymcserver.tld" //Only included when a hostname is detected

Information about debug values

Name Description
ping If the Server List Ping (SLP) protocol was used. Added in version 1.7 and can not be turned off.
query If the Query protocol was used. Default is off.
srv If a Service record (SRV) was detected and used. They use the following format: _minecraft._tcp.domain.tld
querymismatch If the game port returned by the query protocol is not the same port as the Minecraft server is running on, the API assumes the query comes from another server.
You should always set the query port to the same as the Minecraft server.
ipinsrv If an IP was detected in the SRV record. SRV records shoul only contain A/AAAA records.
animatedmotd If an AnimatedMOTD plugin was detected. This changes the ping response in bad ways. The API will try to compensate, but it might not be correct.
proxypipe If ProxyPipe was detected. They will only allow ping on the hostname, which slows lookup time a bit.
cachetime UNIX timestamp of the time the result was cached. Returns 0 when result is not cached.


Version Changes
2 offline: true has been removed from the offline response and replaced with online: false
online: true is now returned when the server is online.
1 Initial version.


If the API does not give the correct result, or maybe not any result, please first check if the server is working in Minecraft.

If the server is working, try the following debug endpoints for ping and query:

Please note: Only use these endpoints for debugging purposes. Use the main API for normal day-to-day use.

If they give the correct output, you might have found a bug in the API. Please report it via email here: api@mcsrvstat.us.

Copyright © 2019 Anders G. Jørgensen - spirit55555.dk - API-MCSRVSTATUS-f4e8529