Minecraft API

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 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.

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

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

Usage

Images