mcstatus - Minecraft Server Status

Common errors

• NameError: name 'MinecraftServer' is not defined

  cause 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

  cause 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

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

Warnings

• breaking The 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.
• breaking The 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.
• breaking Asynchronous 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()`).
• deprecated The `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.
• gotcha The `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.

Install

• pip install mcstatus Install stable version

Imports

• JavaServer

  from mcstatus import JavaServer

• BedrockServer

  from mcstatus import BedrockServer

• MinecraftServer
  wrong:

  from mcstatus import MinecraftServer

  correct:

  from mcstatus import JavaServer

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

Quickstart

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