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: ClassVar[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 BaseJavaServer(host: str, port: int | None = None, timeout: float = 3)[source]

Bases: MCServer

Base class for a Minecraft Java Edition server.

Added in version 12.1.0.

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: ClassVar[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.

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

Bases: BaseJavaServer

Base class for a 1.7+ 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.

  • query_port – Typically the same as port but can be different.

ping(*, tries: int = 3, version: int = 47, ping_token: int | None = None) → float[source]

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

Note that most non-vanilla implementations fail to respond to a ping packet unless a status packet is sent first. Expect OSError: Server did not respond with any information! in those cases. The workaround is to use the latency provided with status() as ping time.

Parameters:
Returns:

The latency between the Minecraft Server and you.

async async_ping(*, tries: int = 3, version: int = 47, ping_token: int | None = None) → float[source]

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

Note that most non-vanilla implementations fail to respond to a ping packet unless a status packet is sent first. Expect OSError: Server did not respond with any information! in those cases. The workaround is to use the latency provided with async_status() as ping time.

Parameters:
Returns:

The latency between the Minecraft Server and you.

status(*, tries: int = 3, version: int = 47, ping_token: int | None = None) → JavaStatusResponse[source]

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

Parameters:
Returns:

Status information in a JavaStatusResponse instance.

async async_status(*, tries: int = 3, version: int = 47, ping_token: int | None = None) → JavaStatusResponse[source]

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

Parameters:
Returns:

Status information in a JavaStatusResponse instance.

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

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

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

Bases: BaseJavaServer

Base class for a pre-1.7 Minecraft Java Edition server.

Added in version 12.1.0.

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.

status(*, tries: int = 3) → LegacyStatusResponse[source]

Check the status of a pre-1.7 Minecraft Java Edition server.

Parameters:

tries – The number of times to retry if an error is encountered.

Returns:

Status information in a LegacyStatusResponse instance.

async async_status(*, tries: int = 3) → LegacyStatusResponse[source]

Asynchronously check the status of a pre-1.7 Minecraft Java Edition server.

Parameters:

tries – The number of times to retry if an error is encountered.

Returns:

Status information in a LegacyStatusResponse instance.

final 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: ClassVar[int] = 19132
status(*, tries: int = 3) → BedrockStatusResponse[source]

Check the status of a Minecraft Bedrock Edition server.

Parameters:

tries – The number of times to retry if an error is encountered.

Returns:

Status information in a BedrockStatusResponse instance.

async async_status(*, tries: int = 3) → BedrockStatusResponse[source]

Asynchronously check the status of a Minecraft Bedrock Edition server.

Parameters:

tries – The number of times to retry if an error is encountered.

Returns:

Status information in a BedrockStatusResponse instance.

Response Objects

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

For Java Server (1.7+)

class JavaStatusResponse[source]

The response object for JavaServer.status().

raw: RawJavaResponse

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.

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

as_dict() → dict[str, Any]

Return the dataclass as JSON-serializable dict.

Do note that this method doesn’t return string but dict, so you can do some processing on returned value.

Difference from raw is in that, raw returns raw response in the same format as we got it. This method returns the response in a more user-friendly JSON serializable format (for example, motd is returned as a Minecraft string and not dict).

property description: str

Alias to the mcstatus.motd.Motd.to_minecraft() method.

motd

Message Of The Day. Also known as description.

See also

MOTD Parsing.

latency

Latency between a server and the client (you). In milliseconds.

class JavaStatusPlayers[source]

Class for storing information about players on the server.

sample: list[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.

online: int

Current number of online players.

max: int

The maximum allowed number of players (aka server slots).

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

raw: RawQueryResponse

Raw response from the server.

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

motd: Motd

The MOTD of the server. Also known as description.

See also

MOTD Parsing.

map_name: str

The name of the map. Default is world.

players: QueryPlayers

The players information.

software: QuerySoftware

The software information.

ip: str

The IP address the server is listening/was contacted on.

port: int

The port the server is listening/was contacted on.

game_type: str = 'SMP'

The game type of the server. Hardcoded to SMP (survival multiplayer).

game_id: str = 'MINECRAFT'

The game ID of the server. Hardcoded to MINECRAFT.

as_dict() → dict[str, Any][source]

Return the dataclass as JSON-serializable dict.

Do note that this method doesn’t return string but dict, so you can do some processing on returned value.

Difference from raw is in that, raw returns raw response in the same format as we got it. This method returns the response in a more user-friendly JSON serializable format (for example, motd is returned as a Minecraft string and not dict).

class QueryPlayers[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).

list: list[str]

The list of online players.

class QuerySoftware[source]

Class for storing information about software on the server.

version: str

The version of the software.

brand: str

The brand of the software. Like Paper or Spigot.

plugins: list[str]

The list of plugins. Can be an empty list if hidden.

Forge Data

Forge mod metadata is available on status.forge_data.

class ForgeData[source]

Class for storing information about Forge mods.

fml_network_version: int

Forge Mod Loader network version.

channels: list[ForgeDataChannel]

List of channels, both for mods and non-mods.

mods: list[ForgeDataMod]

List of mods.

truncated: bool

Is the mods list and or channel list incomplete?

class ForgeDataChannel[source]

A single Forge data channel.

name: str

Channel name and ID (for example fml:handshake).

version: str

Channel version (for example 1.2.3.4).

required: bool

Is this channel required for client to join?

class ForgeDataMod[source]

A single Forge mod.

name: str

A mod name.

marker: str

A mod marker. Usually a version.

For Java Server (Beta 1.8-1.6)

Added in version 12.1.0.

Added in version 13.0.0: Support for Beta 1.8+ (before was 1.4+)

class LegacyStatusResponse[source]

The response object for LegacyServerStatus.status().

players: LegacyStatusPlayers

The players information.

version: LegacyStatusVersion

The version information, only populates for servers >=12w42b (1.4 onwards).

as_dict() → dict[str, Any]

Return the dataclass as JSON-serializable dict.

Do note that this method doesn’t return string but dict, so you can do some processing on returned value.

Difference from raw is in that, raw returns raw response in the same format as we got it. This method returns the response in a more user-friendly JSON serializable format (for example, motd is returned as a Minecraft string and not dict).

property description: str

Alias to the mcstatus.motd.Motd.to_minecraft() method.

motd

Message Of The Day. Also known as description.

See also

MOTD Parsing.

latency

Latency between a server and the client (you). In milliseconds.

class LegacyStatusPlayers[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 LegacyStatusVersion[source]

A class for storing version information.

name: str

The version name, like 1.19.3.

See Minecraft wiki for complete list.

Will be <1.4 for older releases, as those did not send version information.

protocol: int

The protocol version, like 761.

See Minecraft wiki.

-1 means 1.3 and lower, before 1.4 servers did not send information about its version.

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.

as_dict() → dict[str, Any]

Return the dataclass as JSON-serializable dict.

Do note that this method doesn’t return string but dict, so you can do some processing on returned value.

Difference from raw is in that, raw returns raw response in the same format as we got it. This method returns the response in a more user-friendly JSON serializable format (for example, motd is returned as a Minecraft string and not dict).

property description: str

Alias to the mcstatus.motd.Motd.to_minecraft() method.

motd

Message Of The Day. Also known as description.

See also

MOTD Parsing.

latency

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!