mcstatus

library13.1.0pypypi✓ verified 85d ago

mcstatus is a Python library designed to query Minecraft servers (Java Edition and Bedrock Edition) for their status and capabilities, including player counts, server version, MOTD, and latency. It supports both synchronous and asynchronous operations. The current version is 13.0.1 and it's actively maintained with regular updates.

http-networking

pip install mcstatus

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MCSTATUS

mcstatus

http-networkingpythonv13.1.0

Install

1.9s avg

Import

462ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v13.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.485s · 21MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.9s · import 0.439s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

JavaServer

✓ from mcstatus import JavaServer

BedrockServer

✓ from mcstatus import BedrockServer

MinecraftServer

✓ from mcstatus import JavaServer

✗ from mcstatus import MinecraftServer

The 'MinecraftServer' class was renamed to 'JavaServer' in version 10.0.0. For Bedrock Edition servers, use 'BedrockServer'.

This example demonstrates how to asynchronously connect to a Minecraft Java Edition server, retrieve its status, and print key information like version, player count, and latency. It uses `asyncio.run` for a runnable async entry point.

from mcstatus import JavaServer import asyncio async def get_server_status(host, port): try: # 'lookup' can infer the port if not provided for default Minecraft Java port server = await JavaServer.async_lookup(f"{host}:{port}") status = await server.async_status() # Use async_status for async context print(f"Minecraft Java Server at {host}:{port}") print(f" Version: {status.version.name}") print(f" Players: {status.players.online}/{status.players.max}") print(f" Latency: {status.latency:.2f}ms") print(f" MOTD: {status.description}") except Exception as e: print(f"Could not get status for {host}:{port}: {e}") if __name__ == '__main__': # Replace with your server details target_host = "play.hypixel.net" # Example public server target_port = 25565 asyncio.run(get_server_status(target_host, target_port))

mcstatus --version

Debug

Known issues

breakingThe primary class for Java Edition servers was renamed from `MinecraftServer` to `JavaServer` in version 10.0.0. A new `BedrockServer` class was introduced for Bedrock Edition.

fix

Update your imports from `from mcstatus import MinecraftServer` to `from mcstatus import JavaServer` for Java Edition servers, or `from mcstatus import BedrockServer` for Bedrock Edition.

affects: >=10.0.0

breakingThe Python version requirement has been updated multiple times. As of version 13.0.1, it requires Python >=3.10. Older versions of Python are no longer supported.

fix

Ensure your environment uses Python 3.10 or newer. Consider using a virtual environment and updating your Python interpreter if needed.

affects: >=13.0.0

breakingAsynchronous methods (e.g., `async_status`, `async_query`, `async_handshake`) were changed in v10.0.0. They are now named `status`, `query`, `handshake` (without the `async_` prefix) and are directly awaitable. The old `async_` prefixed methods were removed.

fix

Remove the `async_` prefix when calling asynchronous methods (e.g., `await server.status()` instead of `await server.async_status()`).

affects: >=10.0.0

deprecatedThe `MinecraftServer.ping()` method was removed in version 10.0.0. Its functionality is now integrated into the `status()` method.

fix

Instead of `server.ping()`, use `server.status().latency` to retrieve the ping value.

affects: >=10.0.0

gotchaThe `status().latency` attribute, which provides the server ping, changed its return type in version 10.0.0. It now returns a `float` representing milliseconds, instead of a `datetime.timedelta` object.

fix

Adjust any code expecting `timedelta` operations on the `latency` value. It is now a simple numeric value in milliseconds.

affects: >=10.0.0

Errors

Common errors & fixes

NameError: name 'MinecraftServer' is not defined

Attempting to use the old `MinecraftServer` class name, which was renamed in mcstatus v10.0.0.

fix

Update your import and class usage to `JavaServer` for Java Edition servers, or `BedrockServer` for Bedrock Edition servers (e.g., `from mcstatus import JavaServer` and `server = JavaServer.lookup(...)`).

mcstatus.exceptions.MinecraftServerTimeoutError: Could not connect to the server

The server address or port is incorrect, the server is offline, or a firewall is blocking the connection. This often indicates the server is not reachable.

fix

Double-check the server IP address and port. Verify the Minecraft server is running and accessible from your network. Check local firewall settings on both the client and server machines.

TypeError: 'coroutine' object is not callable

This error occurs when an asynchronous method (like `status()`) is called in an `async` function without the `await` keyword, making Python try to treat the coroutine object itself as a function.

fix

Ensure you `await` asynchronous calls, e.g., `status = await server.status()` instead of `status = server.status()`.

Upgrade

Version history

13.1.0latest on PyPI · released Apr 20, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/py-mine/mcstatus ↗

packagehttps://pypi.org/project/mcstatus/ ↗

docshttps://mcstatus.readthedocs.io ↗