minecraft-server-status 0.0.2

Python package for fetching Minecraft Java and Bedrock server status, players, version, and plugins.

minecraft_server_status

A lightweight Python package to fetch Minecraft Java and Minecraft Bedrock server status using the public mcstatus.io API.

This package provides simple classes and methods to check whether a server is online, view player counts, server version, plugins, software, and more — without handling raw HTTP requests yourself.

---

Features

• Supports Minecraft Java Edition
• Supports Minecraft Bedrock Edition
• TTL-based caching (auto refresh after set time)
• Fail-safe network handling (doesn’t crash on request errors)
• Configurable timeout & TTL
• Clean and simple method-based access
• Full raw JSON access available
• Minimal dependency (requests only)

---

Installation

Once published to PyPI:

pip install minecraft-server-status

For local development:

pip install -e .

---

Requirements

• Python 3.9+
• requests

---

Project Structure

minecraft_server_status/
│
├── pyproject.toml
├── README.md
├── LICENSE
└── src/
    └── minecraft_server_status/
        ├── __init__.py
        ├── java.py
        └── bedrock.py

---

Quick Start

Java Server Example

from minecraft_server_status import Java

# ttl = cache time in seconds (default 10)
server = Java("hypixel.net", ttl=15)

print(server.status())                 # True / False
print(server.players())                # Player information
print(server.java_minecraft_version()) # Version details
print(server.plugins())                # Plugin list
print(server.raw())                    # Full JSON response

---

Bedrock Server Example

from minecraft_server_status import Bedrock

server = Bedrock("play.example.com", ttl=20)

print(server.status())
print(server.players())
print(server.server_minecraft_version())
print(server.software())
print(server.raw())

---

TTL Caching Explained

TTL (Time To Live) controls how often the API is called.

Example:

server = Java("hypixel.net", ttl=30)

• First call → Fetches API
• Next calls within 30 sec → Uses cached data
• After 30 sec → Auto refreshes

This prevents:

• API spam
• Rate limits
• Slow performance

---

Error Handling

If the API request fails:

• The package does not crash
• Old cached data is reused
• If no previous data exists → returns:

{"online": False, "error": "..."}

---

Java Class Methods

Method	Description
status()	Returns online status
ip()	Resolved IP address
expires_at()	Cache expiration timestamp
srv_record()	SRV record information
java_minecraft_version()	Minecraft version data
players()	Player count & sample list
message_of_the_day()	Server MOTD
icon()	Base64 server icon
mods()	Installed mods
software()	Server software name
plugins()	Plugin list
raw()	Full API JSON

---

Bedrock Class Methods

Method	Description
status()	Online status
ip_address()	Resolved IP
port_number()	Server port
expires_at()	Cache expiration timestamp
server_minecraft_version()	Version details
players()	Player data
gameMode()	Current game mode
server_id()	Unique server ID
edition()	Bedrock edition info
software()	Server software
plugins()	Plugin list
raw()	Full API JSON

---

How It Works

• Uses https://api.mcstatus.io internally
• Data is cached with TTL
• Network errors are handled gracefully
• Multiple method calls do not trigger multiple API requests
• Designed for bots, dashboards, and quick checks

---

Notes

• If a field is unavailable, the method returns None
• Not intended for high-frequency real-time monitoring
• Depends on the availability of the mcstatus.io API

---

License

MIT License — see LICENSE file.

---

Author

Arpit Jaiswal

GitHub: https://github.com/Arp1it

---

Contributing

Pull requests, bug reports, and improvements are welcome 🚀