A simple way to check the status of a server, along with the number of players currently online.

We've currently gotten requests!

Having issues? Tweet me if anything is broken!


All requests should be sent to /server/status. 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, data is cached server side for five 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.

<script src="https://mcapi.us/scripts/minecraft.js"></script>
<div class="server-status">
  My awesome server is currently <span class="server-online"></span>!
  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';

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.

If something doesn't work or you're interested in a new feature, mention me on Twitter or send me an email!