Basic Usage¶

We are small package, so our API is not so big. There are only few classes, which are suggested for a basic usage.

Request Classes¶

These are classes, that you use to send a request to server.

class MCServer(host: str, port: int | None = None, timeout: float = 3)[source]¶

Bases: ABC

Base abstract class for a general minecraft server.

This class only contains the basic logic shared across both java and bedrock versions, it doesn’t include any version specific settings and it can’t be used to make any requests.

Parameters:

host – The host/ip of the minecraft server.
port – The port that the server is on.
timeout – The timeout in seconds before failing to connect.

DEFAULT_PORT: int¶

classmethod lookup(address: str, timeout: float = 3) → Self[source]¶

Mimics minecraft’s server address field.

Parameters:

address – The address of the Minecraft server, like example.com:19132
timeout – The timeout in seconds before failing to connect.

class JavaServer(host: str, port: int | None = None, timeout: float = 3)[source]¶

Bases: MCServer

Base class for a Minecraft Java Edition server.

Parameters:

host – The host/ip of the minecraft server.
port – The port that the server is on.
timeout – The timeout in seconds before failing to connect.

DEFAULT_PORT: int = 25565¶

classmethod lookup(address: str, timeout: float = 3) → Self[source]¶

Mimics minecraft’s server address field.

With Java servers, on top of just parsing the address, we also check the DNS records for an SRV record that points to the server, which is the same behavior as with minecraft’s server address field for Java. This DNS record resolution is happening synchronously (see async_lookup()).

Parameters:

address – The address of the Minecraft server, like example.com:25565.
timeout – The timeout in seconds before failing to connect.

async classmethod async_lookup(address: str, timeout: float = 3) → Self[source]¶

Asynchronous alternative to lookup().

For more details, check the JavaServer.lookup() docstring.

ping(**kwargs) → float[source]¶

Checks the latency between a Minecraft Java Edition server and the client (you).

Parameters:: kwargs – Passed to a ServerPinger instance.
Returns:: The latency between the Minecraft Server and you.

async async_ping(**kwargs) → float[source]¶

Asynchronously checks the latency between a Minecraft Java Edition server and the client (you).

Parameters:: kwargs – Passed to a AsyncServerPinger instance.
Returns:: The latency between the Minecraft Server and you.

status(**kwargs) → JavaStatusResponse[source]¶

Checks the status of a Minecraft Java Edition server via the status protocol.

Parameters:: kwargs – Passed to a ServerPinger instance.
Returns:: Status information in a JavaStatusResponse instance.

async async_status(**kwargs) → JavaStatusResponse[source]¶

Asynchronously checks the status of a Minecraft Java Edition server via the status protocol.

Parameters:: kwargs – Passed to a AsyncServerPinger instance.
Returns:: Status information in a JavaStatusResponse instance.

query(*, tries: int = 3) → QueryResponse[source]¶

Checks the status of a Minecraft Java Edition server via the query protocol.

Parameters:: tries – The number of times to retry if an error is encountered.
Returns:: Query information in a QueryResponse instance.

async async_query(*, tries: int = 3) → QueryResponse[source]¶

Asynchronously checks the status of a Minecraft Java Edition server via the query protocol.

Parameters:: tries – The number of times to retry if an error is encountered.
Returns:: Query information in a QueryResponse instance.

class BedrockServer(host: str, port: int | None = None, timeout: float = 3)[source]¶

Bases: MCServer

Base class for a Minecraft Bedrock Edition server.

Parameters:

host – The host/ip of the minecraft server.
port – The port that the server is on.
timeout – The timeout in seconds before failing to connect.

DEFAULT_PORT: int = 19132¶

status(**kwargs) → BedrockStatusResponse[source]¶

Checks the status of a Minecraft Bedrock Edition server.

Parameters:: kwargs – Passed to a BedrockServerStatus instance.
Returns:: Status information in a BedrockStatusResponse instance.

async async_status(**kwargs) → BedrockStatusResponse[source]¶

Asynchronously checks the status of a Minecraft Bedrock Edition server.

Parameters:: kwargs – Passed to a BedrockServerStatus instance.
Returns:: Status information in a BedrockStatusResponse instance.

Response Objects¶

These are the classes that you get back after making a request.

For Java Server¶

class JavaStatusResponse[source]¶

The response object for JavaServer.status().

raw: dict¶

Raw response from the server.

This is TypedDict actually, please see sources to find what is here.

players: JavaStatusPlayers¶: The players information.

version: JavaStatusVersion¶: The version information.

enforces_secure_chat: bool | None¶: Whether the server enforces secure chat (every message is signed up with a key).

See also

Signed Chat explanation, 22w17a changelog, where this was added.

New in version 11.1.0.

icon: str | None¶: The icon of the server. In Base64 encoded PNG image format.

See also

How to get server image?

forge_data: ForgeData | None¶: Forge mod data (mod list, channels, etc). Only present if this is a forge (modded) server.

property description: str¶: Alias to the mcstatus.motd.Motd.to_minecraft() method.

motd: Motd¶: Message Of The Day. Also known as description.

See also

MOTD Parsing.

latency: float¶: Latency between a server and the client (you). In milliseconds.

class JavaStatusPlayers[source]¶

Class for storing information about players on the server.

online: int¶: Current number of online players.

max: int¶: The maximum allowed number of players (aka server slots).

sample: list[mcstatus.status_response.JavaStatusPlayer] | None¶

List of players, who are online. If server didn’t provide this, it will be None.

Actually, this is what appears when you hover over the slot count on the multiplayer screen.

Note

It’s often empty or even contains some advertisement, because the specific server implementations or plugins can disable providing this information or even change it to something custom.

There is nothing that mcstatus can to do here if the player sample was modified/disabled like this.

class JavaStatusPlayer[source]¶

Class with information about a single player.

name: str¶: Name of the player.

id: str¶: ID of the player (in UUID format).

property uuid: str¶: Alias to id field.

class JavaStatusVersion[source]¶

A class for storing version information.

name: str¶

The version name, like 1.19.3.

See Minecraft wiki for complete list.

protocol: int¶

The protocol version, like 761.

See Minecraft wiki.

class QueryResponse[source]¶

The response object for JavaServer.query().

class Players[source]¶

Class for storing information about players on the server.

online: int¶: The number of online players.

max: int¶: The maximum allowed number of players (server slots).

names: list[str]¶: The list of online players.

class Software[source]¶

Class for storing information about software on the server.

version: str¶: The version of the software.

brand: str = "vanilla"¶: The brand of the software. Like Paper or Spigot.

plugins: list[str]¶: The list of plugins. Can be empty if hidden.

motd: Motd¶: The MOTD of the server. Also known as description.

See also

MOTD Parsing.

map: str¶: The name of the map.

players: Players¶: The players information.

software: Software¶: The software information.

For Bedrock Servers¶

class BedrockStatusResponse[source]¶

The response object for BedrockServer.status().

players: BedrockStatusPlayers¶: The players information.

version: BedrockStatusVersion¶: The version information.

map_name: str | None¶: The name of the map.

gamemode: str | None¶: The name of the gamemode on the server.

property description: str¶: Alias to the mcstatus.motd.Motd.to_minecraft() method.

motd: Motd¶: Message Of The Day. Also known as description.

See also

MOTD Parsing.

latency: float¶: Latency between a server and the client (you). In milliseconds.

class BedrockStatusPlayers[source]¶

Class for storing information about players on the server.

online: int¶: Current number of online players.

max: int¶: The maximum allowed number of players (aka server slots).

class BedrockStatusVersion[source]¶

A class for storing version information.

protocol: int¶

The protocol version, like 761.

See Minecraft wiki.

name: str¶

The version name, like 1.19.60.

See Minecraft wiki for complete list.

brand: str¶: MCPE or MCEE for Education Edition.

Conclusion¶

That is all! See also our examples!