Skip to main content

MCStatus

discord chat supported python versions current PyPI version Docs CI status

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 (1.7+)

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)}")

Java Edition (Beta 1.8-1.6)

from mcstatus import LegacyServer

# 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 LegacyServer("example.org", 1234)
server = LegacyServer.lookup("example.org:1234")

# 'status' is supported by all Minecraft servers.
status = server.status()
print(f"The server has {status.players.online} player(s) online and replied in {status.latency} ms")

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")

# Bedrock servers speak RakNet (UDP) or NetherNet (TCP, default since 26.50). Both are tried by default;
# pin one with BedrockServer.lookup("example.org:19132", transport="nethernet") to send a single probe.
# '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.

Metadata

Release files for mcstatus 15.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcstatus 15.0.0
File Size Uploaded Provenance Actions
mcstatus-15.0.0.tar.gz 176.3 kB With provenance Details for mcstatus-15.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcstatus 15.0.0
File Interpreter ABI Platform Actions
mcstatus-15.0.0-py3-none-any.whl Python 3 none any Details for mcstatus-15.0.0-py3-none-any.whl

Total release size: 243.2 kB

Release files / mcstatus-15.0.0.tar.gz

Download URL mcstatus-15.0.0.tar.gz
Size 176.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e9e862781f8291f3b715c339c396bc7e6b236f1da948680a90cf237f3d0f1170
BLAKE2b-256 checksum
How to use checksums
355c88222f893412c862a71bd8c3cd56f1c2fbded6974e1044926ba1a923340c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / mcstatus-15.0.0-py3-none-any.whl

Download URL mcstatus-15.0.0-py3-none-any.whl
Size 66.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04187ca016f50c94232b1ce45f20dcdf2bf64cd6768413bb28c975ae1c1103c2
BLAKE2b-256 checksum
How to use checksums
8a515ccbdd9eba516a538ffce69e208b0da20e617bb912d168ee4eb26cb18ebf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for mcstatus 15.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcstatus-15.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

15.0.0 This release

2 release files Full provenance

1.0dev

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page