mcsrvstatus 1.0.3

Python library for working with the mcsrvstat.us API - a service for checking the status of Minecraft servers

mcsrvstatus

A Python library for interacting with the mcsrvstat.us API to check Minecraft server status.

Features

• Check Java and Bedrock Minecraft server status
• Get player count, server version, and MOTD
• Retrieve server icons
• Both synchronous and asynchronous support
• Simple and intuitive API
• Comprehensive error handling

Installation

pip install mcsrvstatus

Quick Start

Synchronous Usage

from mcsrvstatus import MinecraftServerStatus

client = MinecraftServerStatus()

# Check if server is online
is_online = client.is_server_online("mc.hypixel.net")
print(f"Server online: {is_online}")

# Get full server status
status = client.get_server_status("mc.hypixel.net")
print(f"Players: {status['players']['online']}/{status['players']['max']}")

client.close()

Asynchronous Usage

import asyncio
from mcsrvstatus import AsyncMinecraftServerStatus

async def main():
    async with AsyncMinecraftServerStatus() as client:
        is_online = await client.is_server_online("mc.hypixel.net")
        print(f"Server online: {is_online}")
        
        status = await client.get_server_status("mc.hypixel.net")
        print(f"Players: {status['players']['online']}/{status['players']['max']}")

asyncio.run(main())

API Reference

MinecraftServerStatus (Sync)

Methods

get_server_status(server_address: str, version: int = 3) -> Dict[str, Any]

Get full server status information.

status = client.get_server_status("play.example.com")
print(status)
# {
#   "online": True,
#   "ip": "192.168.1.1",
#   "port": 25565,
#   "players": {"online": 50, "max": 100, "list": ["player1", "player2"]},
#   "version": "1.20.1",
#   "motd": {"clean": ["Welcome to our server!"]},
#   "icon": "data:image/png;base64,..."
# }

get_bedrock_status(server_address: str, version: int = 3) -> Dict[str, Any]

Get Bedrock server status.

status = client.get_bedrock_status("play.example.com")

is_server_online(server_address: str) -> bool

Check if server is online.

online = client.is_server_online("play.example.com")

get_player_count(server_address: str) -> Tuple[int, int]

Get current and maximum player count.

online_players, max_players = client.get_player_count("play.example.com")

get_server_version(server_address: str) -> Optional[str]

Get server version.

version = client.get_server_version("play.example.com")

get_server_motd(server_address: str) -> Optional[str]

Get server message of the day.

motd = client.get_server_motd("play.example.com")

get_player_list(server_address: str) -> List[str]

Get list of online players (if available).

players = client.get_player_list("play.example.com")

get_server_icon(server_address: str) -> Optional[str]

Get server icon as base64 string.

icon = client.get_server_icon("play.example.com")

AsyncMinecraftServerStatus (Async)

All methods are the same as the sync version but with async/await:

async with AsyncMinecraftServerStatus() as client:
    status = await client.get_server_status("play.example.com")
    online = await client.is_server_online("play.example.com")
    players = await client.get_player_count("play.example.com")

Error Handling

The library raises specific exceptions for different error cases:

from mcsrvstatus.exceptions import ServerNotFoundError, APIError, ConnectionError

try:
    status = client.get_server_status("nonexistent.server.com")
except ServerNotFoundError:
    print("Server is offline or doesn't exist")
except APIError as e:
    print(f"API error: {e}")
except ConnectionError as e:
    print(f"Network error: {e}")

Examples

Basic Server Information

from mcsrvstatus import MinecraftServerStatus

client = MinecraftServerStatus()

server = "mc.hypixel.net"

try:
    # Basic info
    print(f"Checking {server}...")
    
    if client.is_server_online(server):
        online, max_players = client.get_player_count(server)
        version = client.get_server_version(server)
        motd = client.get_server_motd(server)
        
        print(f"✓ Online: {online}/{max_players} players")
        print(f"✓ Version: {version}")
        print(f"✓ MOTD: {motd}")
    else:
        print("✗ Server is offline")

finally:
    client.close()

Multiple Servers Check

import asyncio
from mcsrvstatus import AsyncMinecraftServerStatus

async def check_servers():
    servers = [
        "mc.hypixel.net",
        "play.mineplex.com", 
        "hub.mcs.gg"
    ]
    
    async with AsyncMinecraftServerStatus() as client:
        tasks = []
        for server in servers:
            task = asyncio.create_task(check_single_server(client, server))
            tasks.append(task)
        
        await asyncio.gather(*tasks)

async def check_single_server(client, server):
    try:
        if await client.is_server_online(server):
            online, max_players = await client.get_player_count(server)
            print(f"{server}: {online}/{max_players} players")
        else:
            print(f"{server}: Offline")
    except Exception as e:
        print(f"{server}: Error - {e}")

asyncio.run(check_servers())

Bedrock Server

from mcsrvstatus import MinecraftServerStatus

client = MinecraftServerStatus()

try:
    status = client.get_bedrock_status("play.nethergames.org")
    print(f"Bedrock server online: {status['online']}")
    print(f"Players: {status['players']['online']}/{status['players']['max']}")
except Exception as e:
    print(f"Error: {e}")
finally:
    client.close()

Context Manager Usage

from mcsrvstatus import MinecraftServerStatus

# Automatically handles connection cleanup
with MinecraftServerStatus() as client:
    status = client.get_server_status("play.example.com")
    print(f"Server: {status['ip']}:{status['port']}")

API Versions

The mcsrvstat.us API supports versions 1, 2, and 3 (default). You can specify the version:

# Use API version 2
status = client.get_server_status("play.example.com", version=2)

Requirements

• Python 3.6+
• requests (for sync client)
• aiohttp (for async client)

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run tests: python -m pytest
5. Submit a pull request

Changelog

1.0.0

• Initial release
• Sync and async support
• Complete API coverage
• Comprehensive error handling