API Documentation

NPM Package

You can use the mcstatus-sdk npm package to easily integrate Minecraft server status checks into your Node.js applications.

Installation:

npm install mcstatus-sdk

Usage Example:

const ServerStatus = require('mcstatus-sdk');
const client = new ServerStatus();

async function checkStatus() {
  const javaStatus = await client.getJavaStatus('example.com');
  console.log(javaStatus);

  const bedrockStatus = await client.getBedrockStatus('example.com');
  console.log(bedrockStatus);

  const icon = await client.getServerIcon('example.com');
  console.log(icon);
}

checkStatus();

Java Server Status

Endpoint: /api/status/:serverAddress

Method: GET

Success Response:

{
  "version": {
    "name": "1.16.5",
    "protocol": 754
  },
  "players": {
    "max": 20,
    "online": 5,
    "list": [
      {
        "name": "EducatedSuddenBucket",
        "id": "uuid1"
      },
      {
        "name": "SomeoneElseInTheServer",
        "id": "uuid2"
      }
    ]
  },
  "description": "A Minecraft Server",
  "latency": 123,
  "favicon": "data:image/png;base64,..."
}

Error Responses:

{
  "error": "timeout"
}

{
  "error": "domain_not_found"
}

{
  "error": "offline"
}

Server Icon (Java Only)

Endpoint: /api/png/:serverip

Method: GET

Success Response: Image (PNG)

Error Responses:

{
  "error": "timeout"
}

{
  "error": "domain_not_found"
}

{
  "error": "offline"
}

{
  "error": "no_favicon"
}

{
  "error": "invalid_favicon"
}

{
  "error": "cant_fetch_favicon"
}

Bedrock Server Status

Endpoint: /api/status/bedrock/:serverAddress

Method: GET

Success Response:

{
  "motd": "Dedicated Server",
  "levelName": "Bedrock level",
  "playersOnline": 0,
  "playersMax": 10,
  "gamemode": "Survival",
  "serverId": "13460148391903423507",
  "protocol": "486",
  "version": "1.18.0",
  "latency": 50
}

Error Responses:

{
  "error": "timeout"
}

{
  "error": "domain_not_found"
}

{
  "error": "offline"
}