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.
- Installation
- Java Edition status methods
- API documentation
- Examples
- Get the status of a Java server
- Get the status of a Java server with options
- Get the status of a Bedrock server
- Get the status of a Bedrock server with options
- Query a server
- Query a server with options
- Full query a server
- Full query a server with options
- Scan for LAN games
- Scan for LAN games with options
- Execute console commands with RCON
- Frequently Asked Questions
- Discord server
- License
npm i minecraft-server-util
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.
The entire API of this library is documented within the wiki.
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);
});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);
});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);
});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);
});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);
});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);
});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);
});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);
});const util = require('minecraft-server-util');
util.scanLAN() // Scans for 5 seconds by default
.then((response) => {
console.log(response);
})
.catch((error) => {
console.error(error);
});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);
});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);
});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.
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.
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.
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.
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.
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.