MCAPI.TR Python SDK

The official, typed and zero-dependency Python client for the MCAPI.TR Minecraft Server Status API.

It supports Minecraft Java, legacy Java and Bedrock servers, synchronous and asynchronous applications, discovery endpoints, generated banners, icons and embeddable widgets.

Installation

pip install mcapitr

For local development:

pip install -e .

Python 3.9 or newer is required. The package has no runtime dependencies.

Quick start

from mcapitr import MCAPIClient

with MCAPIClient() as client:
    status = client.server_status("mc.hypixel.net")

print(status["online"])
if status.get("players"):
    print(status["players"]["online"])

Bedrock and legacy Java queries use explicit flags:

bedrock = client.server_status("play.example.net:19132", bedrock=True)
legacy = client.server_status("old.example.net", legacy=True)

Async usage

The async client provides the same API without blocking the event loop:

import asyncio

from mcapitr import AsyncMCAPIClient


async def main() -> None:
    async with AsyncMCAPIClient() as client:
        status = await client.server_status("mc.hypixel.net")
        print(status["version"]["name"])


asyncio.run(main())

Discovery and platform statistics

with MCAPIClient() as client:
    first_page = client.trends(limit=20)
    statistics = client.stats()

    for server in first_page["data"]:
        print(server["address"], server["players_online"])

    if first_page["meta"].get("hasNext"):
        next_page = client.trends(
            limit=20,
            cursor=first_page["meta"]["nextCursor"],
        )

Media URLs and downloads

URL helpers do not perform a network request:

icon_url = client.server_icon_url("mc.hypixel.net", size=128, image_format="webp")
banner_url = client.server_banner_url("mc.hypixel.net", size="large")
widget_url = client.widget_url("mc.hypixel.net", size="large", theme="dark")
motd_url = client.motd_banner_url("&aWelcome to &bMy Server!")

The matching download methods return bytes:

icon = client.server_icon("mc.hypixel.net", size=128)
with open("server-icon.png", "wb") as image_file:
    image_file.write(icon)

Errors

HTTP and connection failures use dedicated exceptions:

from mcapitr import MCAPIClient, RateLimitError, ServerNotFoundError

try:
    status = MCAPIClient().server_status("offline.example.net")
except ServerNotFoundError as error:
    print("Server is offline or unreachable:", error)
except RateLimitError as error:
    print("Retry after:", error.retry_after)

Available exception classes are MCAPIError, NetworkError, APIError, BadRequestError, ServerNotFoundError, RateLimitError and ResponseDecodeError.

Client options

client = MCAPIClient(
    base_url="https://mcapi.tr/api/v1",
    timeout=10.0,
    user_agent="my-discord-bot/1.0",
)

Development

python -m unittest discover -s tests -v
python -m compileall -q src

License

MIT