Awesome Open Source
Awesome Open Source

minecraft-server-util

npm version License npm weekly downloads GitHub open issues Discord server

A Node.js library for Minecraft servers that can retrieve status, perform queries, and RCON into servers. It uses modern Minecraft protocols to support the latest servers and also includes backward compatibility for older versions. This library supports both Java Edition and Bedrock Edition servers, as long as the correct method is used.

Table of Contents

Installation

npm i minecraft-server-util

Java Edition Status Methods

There are several protocol changes over the years of Minecraft that require different implementations to get the status of a Java Edition server. If you are looking to get the status of a Bedrock Edition server, use the statusBedrock() method instead. All of the methods below are exported from the package as a property.

Minecraft Version status() statusFE01FA() statusFE01() statusFE()
1.7.2 - Latest ✔️ ✔️ ✔️
1.6.1 - 1.6.4 ✔️ ✔️ ✔️
1.4.2 - 1.5.2 ✔️ ✔️
Beta 1.8 - 1.3.2 ✔️

✔️ – This status method will work with this Minecraft version.

❌ – This status method will NOT work with this Minecraft version.

❓ – This status method MAY work with this Minecraft version, but is not guaranteed to.

API Documentation

The entire API of this library is documented within the wiki.

Examples

Get the status of a Java server

const util = require('minecraft-server-util');

util.status('play.hypixel.net') // port is default 25565
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Get the status of a Java server with options

const util = require('minecraft-server-util');

util.status('play.hypixel.net', { port: 25565, enableSRV: true, timeout: 5000, protocolVersion: 47 }) // These are the default options
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Get the status of a Bedrock server

Please note that retrieving the status of a Bedrock Edition server is an experimental API that may not work in specific scenarios. If you find any issues, please submit a new issue.

const util = require('minecraft-server-util');

util.statusBedrock('play.hypixel.net') // port is default 19132
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Get the status of a Bedrock server with options

Please note that retrieving the status of a Bedrock Edition server is an experimental API that may not work in specific scenarios. If you find any issues, please submit a new issue.

const util = require('minecraft-server-util');

util.statusBedrock('play.hypixel.net', { port: 19132, enableSRV: true, timeout: 5000 }) // These are the default options, `clientGUID` is set to random bytes
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Query a server

enable-query needs to be enabled in the server.properties file for this to work.

const util = require('minecraft-server-util');

util.query('play.hypixel.net')
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Query a server with options

enable-query needs to be enabled in the server.properties file for this to work.

const util = require('minecraft-server-util');

util.query('play.hypixel.net', { port: 25565, enableSRV: true, timeout: 5000, sessionID: 0 }) // These are the default options
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Full query a server

enable-query needs to be enabled in the server.properties file for this to work. The server will cache the result every 5 seconds.

const util = require('minecraft-server-util');

util.queryFull('play.hypixel.net')
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Full query a server with options

enable-query needs to be enabled in the server.properties file for this to work. The server will cache the result every 5 seconds.

const util = require('minecraft-server-util');

util.queryFull('play.hypixel.net', { port: 25565, enableSRV: true, timeout: 5000, sessionID: 0 }) // These are the default options
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Scan for LAN games

const util = require('minecraft-server-util');

util.scanLAN() // Scans for 5 seconds by default
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Scan for LAN games with options

const util = require('minecraft-server-util');

util.scanLAN({ scanTime: 5000 }) // These are the default options
    .then((response) => {
        console.log(response);
    })
    .catch((error) => {
        console.error(error);
    });

Execute console commands with RCON

rcon.enable needs to be enabled in the server.properties file and the port and password must be known for this to work.

const util = require('minecraft-server-util');

const client = new util.RCON('play.hypixel.net', { port: 25575, enableSRV: true, timeout: 5000, password: 'abc123' }); // These are the default options

client.on('output', (message) => {
    console.log(message);

    // The client must be closed AFTER receiving the message.
    // Closing too early will cause the client to never output
    // any message.
    client.close();
});

client.connect()
    .then(() => client.run('list')) // List all players online
    .catch((error) => {
        console.error(error);
    });

Frequently Asked Questions

These questions below discuss frequently asked questions asked in our Discord server. Please do not ask any basic JavaScript questions that could have been easily answered if you just decided to learn the language first.

How do I check if the server is up/down?

All of the status methods for both Java and Bedrock edition return a promise which resolves to the response. If the promise returned resolves, then the server is online. If the promise rejects, then it was unable to connect to the server, meaning it was likely offline.

How do I browserify/webpack this module?

This module cannot be used in a browser environment because the TCP/UDP protocol has not been implemented. Sure, you could bundle this module successfully but you would run into an error such as Cannot find module 'net' or Cannot find module 'dgram'. The only way of using this module on the browser is to create an API server that proxies the information between a server and the client.

Why am I getting weird values?

The values in the response are all provided by the server that you're requesting it from. This library has no control over what values it receives, thus meaning that it can be any value. If you're getting weird information back, ask the server owner why they're running a plugin that modifies these values.

Why is the sample players array empty?

The sample players array is another value that is controlled entirely by the server, just like the question above. Most vanilla servers have a threshold of how many players can be online before it stops sending any sample players in the status response. If you want a reliable method of getting players, use queryFull() instead.

I'm getting the error util is not a function

This is most likely due to running an old version of this package. Updating your packages without updating code can result in a lot of unexpected errors, which is why you should have read the change log. Look at the examples above.

Discord Server

https://discord.gg/e7jgDYY

License

MIT License


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Java (710,532
Typescript (254,029
Minecraft (7,392
Tcp (1,683
Query (900
Ping (557
Status (388
Bedrock (192
Rcon (134
Related Projects