A simple way to get the status of or query a Minecraft server.

Usage

All requests should be sent to /server/status or /server/query. You may add two parameters, an ip and a port. JSONP is not supported as CORS is enabled.

Please do not send more than one request per client per minute as data is cached server side for a few minutes.

An example request would look like https://mcapi.us/server/status?ip=s.nerd.nu. If you are using a non-standard 25565 port, you may include the port too, like this: https://mcapi.us/server/status?ip=s.nerd.nu&port=25565.

Alternatively, you can use our JavaScript library. Here's a small example of it in use.

<div class="server-status">
    My awesome server is currently <span class="server-online"></span>!
</div>

<script src="https://mcapi.us/scripts/minecraft.min.js"></script>
<script>
    MinecraftAPI.getServerStatus('s.nerd.nu', {
        port: 25565 // optional, only if you need a custom port
    }, function (err, status) {
        if (err) {
            return document.querySelector('.server-status').innerHTML = 'Error loading status';
        }

        // you can change these to your own message!
        document.querySelector('.server-online').innerHTML = status.online ? 'up' : 'down';
    });
</script>

A response from this might look the following (live response data):

name description example
status the status of the request, typically success unless a poor request is made or my server is having internal troubles. if this is not success, assume the data is bad and should not be used. success
online if the server is online or not true
motd the server description, also known as the message of the day. some strange formatting may be in this, there are various libraries available for formatting this. My Minecraft server
error error message from the request. if you forget the IP the error will be missing data. if it is an invalid IP, the error will be invalid hostname or port. if an error starts with internal server error, it means something is wrong with my server. empty means no error.
players.max number of players that the server will allow 20
players.now number of players currently online 2
server.name current server version name Spigot 1.8.3
server.protocol server version protocol 47
last_online the date the server was last recorded online. if empty, it has never been online. it is a unix timestamp in string form. if this has the same value as last_updated, it means that it is currently online. 1431985691
last_updated the date the status of the server was last updated at. it updates every five minutes, so you may send requests as soon as it has expired. 1431985691
duration the time it took to process the original request, in nanoseconds. 143439400

If you're looking for more information about the server, such as what plugins are installed or the name of the players currently online, you can try the /server/query endpoint instead. It takes the same parameters, and can be used with the provided JavaScript library by calling MinecraftAPI.getServerQuery instead.

However, query must be enabled on the server for this to work.

Images

Images can be used on a forum, etc. to show your server's status when you can't use JavaScript.

Just add an image with the source https://mcapi.us/server/image?ip=server_ip to your post or site. If your server has an icon, it will use that. If not, it will show a standard grass block. Add &port=25566 if you're using a non-standard port. If you have a dark background, you can add &theme=dark to the URL and it will make the text white instead. If you prefer to show a different title or IP, you can change the first line of text with &title=YourMessage.

Below is an example of the light and dark themes.