Skip to main content

A library to query Minecraft Servers for their status and capabilities.

Project description

MCStatus

discord chat supported python versions current PyPI version Docs Validation Unit Tests

Mcstatus provides an API and command line script to fetch publicly available data from Minecraft servers. Specifically, mcstatus retrieves data by using these protocols: Server List Ping and Query. Because of mcstatus, you do not need to fully understand those protocols and can instead skip straight to retrieving minecraft server data quickly in your own programs.

Installation

Mcstatus is available on PyPI, and can be installed trivially with:

python3 -m pip install mcstatus

Usage

Python API

Java Edition

from mcstatus import JavaServer

# You can pass the same address you'd enter into the address field in minecraft into the 'lookup' function
# If you know the host and port, you may skip this and use JavaServer("example.org", 1234)
server = JavaServer.lookup("example.org:1234")

# 'status' is supported by all Minecraft servers that are version 1.7 or higher.
# Don't expect the player list to always be complete, because many servers run
# plugins that hide this information or limit the number of players returned or even
# alter this list to contain fake players for purposes of having a custom message here.
status = server.status()
print(f"The server has {status.players.online} player(s) online and replied in {status.latency} ms")

# 'ping' is supported by all Minecraft servers that are version 1.7 or higher.
# It is included in a 'status' call, but is also exposed separate if you do not require the additional info.
latency = server.ping()
print(f"The server replied in {latency} ms")

# 'query' has to be enabled in a server's server.properties file!
# It may give more information than a ping, such as a full player list or mod information.
query = server.query()
print(f"The server has the following players online: {', '.join(query.players.names)}")

Bedrock Edition

from mcstatus import BedrockServer

# You can pass the same address you'd enter into the address field in minecraft into the 'lookup' function
# If you know the host and port, you may skip this and use BedrockServer("example.org", 19132)
server = BedrockServer.lookup("example.org:19132")

# 'status' is the only feature that is supported by Bedrock at this time.
# In this case status includes players.online, latency, motd, map, gamemode, and players.max. (ex: status.gamemode)
status = server.status()
print(f"The server has {status.players.online} players online and replied in {status.latency} ms")

See the documentation to find what you can do with our library!

Command Line Interface

The mcstatus library includes a simple CLI. Once installed, it can be used through:

python3 -m mcstatus --help

License

Mcstatus is licensed under the Apache 2.0 license. See LICENSE for full text.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcstatus-12.0.1.tar.gz (121.6 kB view details)

Uploaded Source

Built Distribution

mcstatus-12.0.1-py3-none-any.whl (43.1 kB view details)

Uploaded Python 3

File details

Details for the file mcstatus-12.0.1.tar.gz.

File metadata

  • Download URL: mcstatus-12.0.1.tar.gz
  • Upload date:
  • Size: 121.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for mcstatus-12.0.1.tar.gz
Algorithm Hash digest
SHA256 5a09a46ff09abaf93ef4c7717a0e7d61bbd8409272dd7b6a5e0f5ca1557a72e4
MD5 16278ce72685c3fd2227fb018f992701
BLAKE2b-256 b458888ae2cb7cff8013f4c85809865c773d37202f23aa9a3fc2831710ff8d43

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcstatus-12.0.1.tar.gz:

Publisher: publish.yml on py-mine/mcstatus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mcstatus-12.0.1-py3-none-any.whl.

File metadata

  • Download URL: mcstatus-12.0.1-py3-none-any.whl
  • Upload date:
  • Size: 43.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for mcstatus-12.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d75cdf8ee78fda750901afad1b7a84864df7f8e29f46e295ac048531a2345e83
MD5 fd0e5f3660faa0e9666baa321068b162
BLAKE2b-256 7cd4b28d999ed6cce5f345533ba3c1b0efd324c0c0c7b905d0a79e388d6b317c

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcstatus-12.0.1-py3-none-any.whl:

Publisher: publish.yml on py-mine/mcstatus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page