mcstatusio package#

Submodules#

mcstatusio.BedrockServer module#

Bedrock Edition Minecraft server status client.

This module provides a client for querying the status of Bedrock Edition Minecraft servers using the mcstatus.io API. It supports both synchronous and asynchronous requests.

class mcstatusio.BedrockServer.BedrockServer(hostname: str, port: int = 19132, timeout: int = 5)[source]#

Bases: object

Client for querying Bedrock Edition Minecraft server status.

This class provides methods to retrieve status information from Bedrock Edition Minecraft servers via the mcstatus.io API. Both synchronous and asynchronous methods are available.

Parameters:

hostname – Server hostname or IP address. Can include port as “hostname:port”
port – Server port (default: 19132, the standard Minecraft Bedrock port)
timeout – Request timeout in seconds (default: 5)

hostname#: The server hostname or IP address

port#: The server port number

timeout#: Request timeout in seconds

Example

>>> server = BedrockServer("play.cubecraft.net", port=19132)
>>> status = server.status()
>>> print(f"Online: {status.online}")
>>> print(f"Players: {status.players.online}/{status.players.max}")

>>> # Using async
>>> import asyncio
>>> async def get_status():
...     server = BedrockServer("play.cubecraft.net")
...     status = await server.async_status()
...     return status
>>> asyncio.run(get_status())

async async_status() → BedrockServerStatusResponse | BedrockServerStatusOffline[source]#

Retrieve the server status asynchronously.

Asynchronously queries the mcstatus.io API to get the current status of the Bedrock Edition Minecraft server. If the hostname contains a port (e.g., “example.com:19133”), it will be parsed and used instead of the default port.

Returns:

BedrockServerStatusResponse if the server is online, containing detailed server information including version, players, MOTD, gamemode, and edition. BedrockServerStatusOffline if the server is offline, containing basic information like port and IP address.

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> import asyncio
>>> async def check_server():
...     server = BedrockServer("play.cubecraft.net")
...     status = await server.async_status()
...     if status.online:
...         print(f"Server is online with {status.players.online} players")
...         print(f"Edition: {status.edition}")
...     else:
...         print("Server is offline")
>>> asyncio.run(check_server())

status() → BedrockServerStatusResponse | BedrockServerStatusOffline[source]#

Retrieve the server status synchronously.

Queries the mcstatus.io API to get the current status of the Bedrock Edition Minecraft server. If the hostname contains a port (e.g., “example.com:19133”), it will be parsed and used instead of the default port.

Returns:

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> server = BedrockServer("play.cubecraft.net")
>>> status = server.status()
>>> if status.online:
...     print(f"Server is online with {status.players.online} players")
...     print(f"Edition: {status.edition}")
... else:
...     print("Server is offline")

class mcstatusio.BedrockServer.BedrockServerStatusResponse(online: bool, port: int, ip_address: str | None, eula_blocked: bool | None, retrieved_at: int | None, expires_at: int | None, version: BedrockVersion, players: BedrockPlayers, motd: MOTD, gamemode: str | None, server_id: str | None, edition: Literal['MCPE', 'MCEE', None])[source]#

Bases: StatusResponse

Response data for an online Bedrock Edition Minecraft server.

Extends StatusResponse with Bedrock Edition-specific information including version details, player information, MOTD, gamemode, and edition type.

version#

Server version information (name and protocol)

Type:: mcstatusio.constants.BedrockVersion

players#

Player count (online and max)

Type:: mcstatusio.constants.BedrockPlayers

motd#

Message of the day (raw, clean, and HTML formats)

Type:: mcstatusio.constants.MOTD

gamemode#

Server gamemode (e.g., “Survival”, “Creative”)

Type:: str | None

server_id#

Unique server identifier

Type:: str | None

edition#

Server edition type (“MCPE” for Pocket Edition, “MCEE” for Education Edition)

Type:: Literal[‘MCPE’, ‘MCEE’, None]

edition: Literal['MCPE', 'MCEE', None]#

gamemode: str | None#

motd: MOTD#

players: BedrockPlayers#

server_id: str | None#

version: BedrockVersion#

mcstatusio.JavaServer module#

Java Edition Minecraft server status client.

This module provides a client for querying the status of Java Edition Minecraft servers using the mcstatus.io API. It supports both synchronous and asynchronous requests.

class mcstatusio.JavaServer.JavaServer(hostname: str, port: int = 25565, timeout: int = 5)[source]#

Bases: object

Client for querying Java Edition Minecraft server status.

This class provides methods to retrieve status information from Java Edition Minecraft servers via the mcstatus.io API. Both synchronous and asynchronous methods are available.

Parameters:

hostname – Server hostname or IP address. Can include port as “hostname:port”
port – Server port (default: 25565, the standard Minecraft Java port)
timeout – Request timeout in seconds (default: 5)

hostname#: The server hostname or IP address

port#: The server port number

timeout#: Request timeout in seconds

Example

>>> server = JavaServer("mc.hypixel.net")
>>> status = server.status()
>>> print(f"Online: {status.online}")
>>> print(f"Players: {status.players.online}/{status.players.max}")

>>> # Using async
>>> import asyncio
>>> async def get_status():
...     server = JavaServer("mc.hypixel.net")
...     status = await server.async_status()
...     return status
>>> asyncio.run(get_status())

async async_status() → JavaServerStatusResponse | JavaServerStatusOffline[source]#

Retrieve the server status asynchronously.

Asynchronously queries the mcstatus.io API to get the current status of the Java Edition Minecraft server. If the hostname contains a port (e.g., “example.com:25566”), it will be parsed and used instead of the default port.

Returns:

JavaServerStatusResponse if the server is online, containing detailed server information including version, players, MOTD, mods, and plugins. JavaServerStatusOffline if the server is offline, containing basic information like hostname, port, and IP address.

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> import asyncio
>>> async def check_server():
...     server = JavaServer("mc.hypixel.net")
...     status = await server.async_status()
...     if status.online:
...         print(f"Server is online with {status.players.online} players")
...     else:
...         print("Server is offline")
>>> asyncio.run(check_server())

status() → JavaServerStatusResponse | JavaServerStatusOffline[source]#

Retrieve the server status synchronously.

Queries the mcstatus.io API to get the current status of the Java Edition Minecraft server. If the hostname contains a port (e.g., “example.com:25566”), it will be parsed and used instead of the default port.

Returns:

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> server = JavaServer("mc.hypixel.net")
>>> status = server.status()
>>> if status.online:
...     print(f"Server is online with {status.players.online} players")
... else:
...     print("Server is offline")

Bases: StatusResponse

Response data for an online Java Edition Minecraft server.

Extends StatusResponse with Java Edition-specific information including version details, player information, MOTD, server mods/plugins, and more.

version#

Server version information (name and protocol)

Type:: mcstatusio.constants.JavaVersion

players#

Player count and sample list

Type:: mcstatusio.constants.JavaPlayers

hostname#

Server hostname

Type:: str | None

motd#

Message of the day (raw, clean, and HTML formats)

Type:: mcstatusio.constants.MOTD

icon#

Base64-encoded server icon (if available)

Type:: str | None

mods#

List of installed mods (if available)

Type:: list[mcstatusio.constants.JavaMods] | None

software#

Server software name (e.g., “Paper”, “Spigot”)

Type:: str | None

plugins#

List of installed plugins (if available)

Type:: list[mcstatusio.constants.JavaPlugins] | None

srv#

SRV record information (if available)

Type:: mcstatusio.constants.JavaSRV | None

hostname: str | None#

icon: str | None#

mods: list[JavaMods] | None#

motd: MOTD#

players: JavaPlayers#

plugins: list[JavaPlugins] | None#

software: str | None#

srv: JavaSRV | None#

version: JavaVersion#

mcstatusio.constants module#

Constants and typed data models for the mcstatusio package.

This module defines all dataclass models used to represent Minecraft server status information for both Java Edition and Bedrock Edition servers. It also provides configuration constants like the base API URL and default timeout values.

Constants:: BASE_URL: The base URL for the mcstatus.io API (v2) DEFAULT_TIMEOUT: Default request timeout in seconds (5)

class mcstatusio.constants.BedrockPlayers(max: int | None, online: int | None)[source]#

Bases: object

Bedrock Edition server player information.

max#

Maximum number of players allowed

Type:: int | None

online#

Number of players currently online

Type:: int | None

max: int | None#

online: int | None#

class mcstatusio.constants.BedrockServerStatusOffline(online: bool, port: int, ip_address: str | None, eula_blocked: bool, retrieved_at: int, expires_at: int)[source]#

Bases: object

Status information for an offline Bedrock Edition server.

Contains basic information that can be retrieved even when the server is not responding.

online#

Always False for offline servers

Type:: bool

port#

Server port

Type:: int

ip_address#

Server IP address (if resolvable)

Type:: str | None

eula_blocked#

Whether the server is EULA blocked

Type:: bool

retrieved_at#

Unix timestamp of retrieval

Type:: int

expires_at#

Unix timestamp of cache expiry

Type:: int

eula_blocked: bool#

expires_at: int#

ip_address: str | None#

online: bool#

port: int#

retrieved_at: int#

class mcstatusio.constants.BedrockVersion(name: str | None, protocol: int | None)[source]#

Bases: object

Bedrock Edition server version information.

name#

Version name string (e.g., “1.20.1”)

Type:: str | None

protocol#

Minecraft protocol version number

Type:: int | None

name: str | None#

protocol: int | None#

class mcstatusio.constants.JavaMods(name: str, version: str)[source]#

Bases: object

Information about a mod installed on a Java Edition server.

name#

Mod name

Type:: str

version#

Mod version string

Type:: str

name: str#

version: str#

class mcstatusio.constants.JavaPlayers(max: int, online: int, list: list[Player] | None)[source]#

Bases: object

Java Edition server player information.

max#

Maximum number of players allowed

Type:: int

online#

Number of players currently online

Type:: int

sample#: List of sample players (if provided by server)

list: list[Player] | None#

max: int#

online: int#

class mcstatusio.constants.JavaPlugins(name: str, version: str)[source]#

Bases: object

Information about a plugin installed on a Java Edition server.

name#

Plugin name

Type:: str

version#

Plugin version string

Type:: str

name: str#

version: str#

class mcstatusio.constants.JavaSRV(host: str, port: int)[source]#

Bases: object

DNS SRV record information for a Java Edition server.

SRV records allow Minecraft servers to use custom ports while still being accessible via the standard domain name.

host#

SRV record target host

Type:: str

port#

SRV record target port

Type:: int

host: str#

port: int#

Bases: object

Status information for an offline Java Edition server.

Contains basic information that can be retrieved even when the server is not responding.

online#

Always False for offline servers

Type:: bool

hostname#

Server hostname

Type:: str | None

port#

Server port

Type:: int

ip_address#

Server IP address (if resolvable)

Type:: str | None

eula_blocked#

Whether the server is EULA blocked

Type:: bool | None

retrieved_at#

Unix timestamp of retrieval

Type:: int | None

expires_at#

Unix timestamp of cache expiry

Type:: int | None

srv#

SRV record information (if available)

Type:: mcstatusio.constants.JavaSRV | None

eula_blocked: bool | None#

expires_at: int | None#

hostname: str | None#

ip_address: str | None#

online: bool#

port: int#

retrieved_at: int | None#

srv: JavaSRV | None#

class mcstatusio.constants.JavaVersion(name: JavaVersionName, protocol: int)[source]#

Bases: object

Java Edition server version information.

name#

Version name in multiple formats

Type:: mcstatusio.constants.JavaVersionName

protocol#

Minecraft protocol version number

Type:: int

name: JavaVersionName#

protocol: int#

class mcstatusio.constants.JavaVersionName(raw: str, clean: str, html: str)[source]#

Bases: object

Java Edition server version name in multiple formats.

raw#

Raw version string with formatting codes

Type:: str

clean#

Clean version string without formatting

Type:: str

html#

HTML-formatted version string

Type:: str

clean: str#

html: str#

raw: str#

class mcstatusio.constants.MOTD(raw: str, clean: str, html: str)[source]#

Bases: object

Message of the Day (MOTD) shown in the server list.

The MOTD is provided in three formats for different use cases.

raw#

Raw MOTD with formatting codes

Type:: str

clean#

Plain text MOTD without formatting

Type:: str

html#

HTML-formatted MOTD for web display

Type:: str

clean: str#

html: str#

raw: str#

class mcstatusio.constants.Player(uuid: UUID | None, raw: str, clean: str, html: str)[source]#

Bases: object

Represents a player connected to the server.

uuid#

Player’s UUID (if available)

Type:: uuid.UUID | None

raw#

Raw player name with formatting codes

Type:: str

clean#

Clean player name without formatting

Type:: str

html#

HTML-formatted player name

Type:: str

clean: str#

html: str#

raw: str#

uuid: UUID | None#

class mcstatusio.constants.StatusResponse(online: bool, port: int, ip_address: str | None, eula_blocked: bool | None, retrieved_at: int | None, expires_at: int | None)[source]#

Bases: object

Base response data for any Minecraft server status query.

This is the parent class for both online and offline server responses, containing common fields that are always present.

online#

Whether the server is currently online

Type:: bool

port#

Server port number

Type:: int

ip_address#

Server IP address (if resolved)

Type:: str | None

eula_blocked#

Whether the server is blocked due to EULA violations

Type:: bool | None

retrieved_at#

Unix timestamp when the status was retrieved

Type:: int | None

expires_at#

Unix timestamp when the cached status expires

Type:: int | None

eula_blocked: bool | None#

expires_at: int | None#

ip_address: str | None#

online: bool#

port: int#

retrieved_at: int | None#

mcstatusio.exceptions module#

Module contents#

mcstatusio - A Python wrapper for the mcstatus.io API.

This package provides simple and efficient interfaces to query Minecraft server status information for both Java Edition and Bedrock Edition servers via the mcstatus.io API.

Classes:: JavaServer: Client for querying Java Edition Minecraft servers BedrockServer: Client for querying Bedrock Edition Minecraft servers

Example

>>> from mcstatusio import JavaServer
>>> server = JavaServer("mc.hypixel.net")
>>> status = server.status()
>>> print(f"Players online: {status.players.online}/{status.players.max}")

class mcstatusio.BedrockServer(hostname: str, port: int = 19132, timeout: int = 5)[source]#

Bases: object

Client for querying Bedrock Edition Minecraft server status.

This class provides methods to retrieve status information from Bedrock Edition Minecraft servers via the mcstatus.io API. Both synchronous and asynchronous methods are available.

Parameters:

hostname – Server hostname or IP address. Can include port as “hostname:port”
port – Server port (default: 19132, the standard Minecraft Bedrock port)
timeout – Request timeout in seconds (default: 5)

hostname#: The server hostname or IP address

port#: The server port number

timeout#: Request timeout in seconds

Example

>>> server = BedrockServer("play.cubecraft.net", port=19132)
>>> status = server.status()
>>> print(f"Online: {status.online}")
>>> print(f"Players: {status.players.online}/{status.players.max}")

>>> # Using async
>>> import asyncio
>>> async def get_status():
...     server = BedrockServer("play.cubecraft.net")
...     status = await server.async_status()
...     return status
>>> asyncio.run(get_status())

async async_status() → BedrockServerStatusResponse | BedrockServerStatusOffline[source]#

Retrieve the server status asynchronously.

Returns:

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> import asyncio
>>> async def check_server():
...     server = BedrockServer("play.cubecraft.net")
...     status = await server.async_status()
...     if status.online:
...         print(f"Server is online with {status.players.online} players")
...         print(f"Edition: {status.edition}")
...     else:
...         print("Server is offline")
>>> asyncio.run(check_server())

status() → BedrockServerStatusResponse | BedrockServerStatusOffline[source]#

Retrieve the server status synchronously.

Returns:

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> server = BedrockServer("play.cubecraft.net")
>>> status = server.status()
>>> if status.online:
...     print(f"Server is online with {status.players.online} players")
...     print(f"Edition: {status.edition}")
... else:
...     print("Server is offline")

class mcstatusio.JavaServer(hostname: str, port: int = 25565, timeout: int = 5)[source]#

Bases: object

Client for querying Java Edition Minecraft server status.

This class provides methods to retrieve status information from Java Edition Minecraft servers via the mcstatus.io API. Both synchronous and asynchronous methods are available.

Parameters:

hostname – Server hostname or IP address. Can include port as “hostname:port”
port – Server port (default: 25565, the standard Minecraft Java port)
timeout – Request timeout in seconds (default: 5)

hostname#: The server hostname or IP address

port#: The server port number

timeout#: Request timeout in seconds

Example

>>> server = JavaServer("mc.hypixel.net")
>>> status = server.status()
>>> print(f"Online: {status.online}")
>>> print(f"Players: {status.players.online}/{status.players.max}")

>>> # Using async
>>> import asyncio
>>> async def get_status():
...     server = JavaServer("mc.hypixel.net")
...     status = await server.async_status()
...     return status
>>> asyncio.run(get_status())

async async_status() → JavaServerStatusResponse | JavaServerStatusOffline[source]#

Retrieve the server status asynchronously.

Returns:

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> import asyncio
>>> async def check_server():
...     server = JavaServer("mc.hypixel.net")
...     status = await server.async_status()
...     if status.online:
...         print(f"Server is online with {status.players.online} players")
...     else:
...         print("Server is offline")
>>> asyncio.run(check_server())

status() → JavaServerStatusResponse | JavaServerStatusOffline[source]#

Retrieve the server status synchronously.

Returns:

Raises:

httpx.HTTPStatusError – If the API request fails
httpx.TimeoutException – If the request times out
httpx.RequestError – For other request-related errors

Example

>>> server = JavaServer("mc.hypixel.net")
>>> status = server.status()
>>> if status.online:
...     print(f"Server is online with {status.players.online} players")
... else:
...     print("Server is offline")

On this page