# mcsrvstatus
 [](https://pypi.org/project/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
```bash
pip install mcsrvstatus
```
## Quick Start
### Synchronous Usage
```python
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
```python
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.
```python
status = client.get_server_status("play.example.com")
print(f"Online: {status.online}")
print(f"IP: {status.ip}:{status.port}")
print(f"Players: {status.players.online}/{status.players.max}")
print(f"Version: {status.version.name}")
print(f"MOTD: {status.motd.text}")
print(f"Player list: {status.players.list}")
```
**`get_bedrock_status(server_address: str, version: int = 3) -> Dict[str, Any]`**
Get Bedrock server status.
```python
status = client.get_bedrock_status("play.example.com")
```
**`is_server_online(server_address: str) -> bool`**
Check if server is online.
```python
online = client.is_server_online("play.example.com")
```
**`get_player_count(server_address: str) -> Tuple[int, int]`**
Get current and maximum player count.
```python
online_players, max_players = client.get_player_count("play.example.com")
```
**`get_server_version(server_address: str) -> Optional[str]`**
Get server version.
```python
version = client.get_server_version("play.example.com")
```
**`get_server_motd(server_address: str) -> Optional[str]`**
Get server message of the day.
```python
motd = client.get_server_motd("play.example.com")
```
**`get_player_list(server_address: str) -> List[str]`**
Get list of online players (if available).
```python
players = client.get_player_list("play.example.com")
```
**`get_server_icon(server_address: str) -> Optional[str]`**
Get server icon as base64 string.
```python
icon = client.get_server_icon("play.example.com")
```
### AsyncMinecraftServerStatus (Async)
All methods are the same as the sync version but with `async`/`await`:
```python
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:
```python
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
```python
from mcsrvstatus import MinecraftServerStatus
client = MinecraftServerStatus()
server = "mc.hypixel.net"
try:
# Basic info
print(f"Checking {server}...")
if client.is_server_online(server):
status = client.get_server_status(server)
print(f"✓ Online: {status.players.online}/{status.players.max} players")
print(f"✓ Version: {status.version.name}")
print(f"✓ MOTD: {status.motd.text}")
else:
print("✗ Server is offline")
finally:
client.close()
```
### Multiple Servers Check
```python
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):
status = await client.get_server_status(server)
print(f"{server}: {status.players.online}/{status.players.max} players")
else:
print(f"{server}: Offline")
except Exception as e:
print(f"{server}: Error - {e}")
asyncio.run(check_servers())
```
### Bedrock Server
```python
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
```python
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:
```python
# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Towux/mcsrvstatus",
"name": "mcsrvstatus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "minecraft, server, status, api, mcsrvstat, bedrock, java, async",
"author": "Towux",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/75/2d/a0dffe13742033c9a08a1458bd27351b6d04ff31a42fdf69e1a203d3acb8/mcsrvstatus-1.0.6.tar.gz",
"platform": null,
"description": "# mcsrvstatus\r\n\r\n [](https://pypi.org/project/mcsrvstatus/) \r\n\r\nA Python library for interacting with the mcsrvstat.us API to check Minecraft server status.\r\n\r\n## Features\r\n\r\n- Check Java and Bedrock Minecraft server status\r\n- Get player count, server version, and MOTD\r\n- Retrieve server icons\r\n- Both synchronous and asynchronous support\r\n- Simple and intuitive API\r\n- Comprehensive error handling\r\n\r\n## Installation\r\n\r\n```bash\r\npip install mcsrvstatus\r\n```\r\n\r\n## Quick Start\r\n\r\n### Synchronous Usage\r\n\r\n```python\r\nfrom mcsrvstatus import MinecraftServerStatus\r\n\r\nclient = MinecraftServerStatus()\r\n\r\n# Check if server is online\r\nis_online = client.is_server_online(\"mc.hypixel.net\")\r\nprint(f\"Server online: {is_online}\")\r\n\r\n# Get full server status\r\nstatus = client.get_server_status(\"mc.hypixel.net\")\r\nprint(f\"Players: {status.players.online}/{status.players.max}\")\r\n\r\nclient.close()\r\n```\r\n\r\n### Asynchronous Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom mcsrvstatus import AsyncMinecraftServerStatus\r\n\r\nasync def main():\r\n async with AsyncMinecraftServerStatus() as client:\r\n is_online = await client.is_server_online(\"mc.hypixel.net\")\r\n print(f\"Server online: {is_online}\")\r\n \r\n status = await client.get_server_status(\"mc.hypixel.net\")\r\n print(f\"Players: {status.players.online}/{status.players.max}\")\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## API Reference\r\n\r\n### MinecraftServerStatus (Sync)\r\n\r\n#### Methods\r\n\r\n**`get_server_status(server_address: str, version: int = 3) -> Dict[str, Any]`**\r\n\r\nGet full server status information.\r\n\r\n```python\r\nstatus = client.get_server_status(\"play.example.com\")\r\nprint(f\"Online: {status.online}\")\r\nprint(f\"IP: {status.ip}:{status.port}\")\r\nprint(f\"Players: {status.players.online}/{status.players.max}\")\r\nprint(f\"Version: {status.version.name}\")\r\nprint(f\"MOTD: {status.motd.text}\")\r\nprint(f\"Player list: {status.players.list}\")\r\n```\r\n\r\n**`get_bedrock_status(server_address: str, version: int = 3) -> Dict[str, Any]`**\r\n\r\nGet Bedrock server status.\r\n\r\n```python\r\nstatus = client.get_bedrock_status(\"play.example.com\")\r\n```\r\n\r\n**`is_server_online(server_address: str) -> bool`**\r\n\r\nCheck if server is online.\r\n\r\n```python\r\nonline = client.is_server_online(\"play.example.com\")\r\n```\r\n\r\n**`get_player_count(server_address: str) -> Tuple[int, int]`**\r\n\r\nGet current and maximum player count.\r\n\r\n```python\r\nonline_players, max_players = client.get_player_count(\"play.example.com\")\r\n```\r\n\r\n**`get_server_version(server_address: str) -> Optional[str]`**\r\n\r\nGet server version.\r\n\r\n```python\r\nversion = client.get_server_version(\"play.example.com\")\r\n```\r\n\r\n**`get_server_motd(server_address: str) -> Optional[str]`**\r\n\r\nGet server message of the day.\r\n\r\n```python\r\nmotd = client.get_server_motd(\"play.example.com\")\r\n```\r\n\r\n**`get_player_list(server_address: str) -> List[str]`**\r\n\r\nGet list of online players (if available).\r\n\r\n```python\r\nplayers = client.get_player_list(\"play.example.com\")\r\n```\r\n\r\n**`get_server_icon(server_address: str) -> Optional[str]`**\r\n\r\nGet server icon as base64 string.\r\n\r\n```python\r\nicon = client.get_server_icon(\"play.example.com\")\r\n```\r\n\r\n### AsyncMinecraftServerStatus (Async)\r\n\r\nAll methods are the same as the sync version but with `async`/`await`:\r\n\r\n```python\r\nasync with AsyncMinecraftServerStatus() as client:\r\n status = await client.get_server_status(\"play.example.com\")\r\n online = await client.is_server_online(\"play.example.com\")\r\n players = await client.get_player_count(\"play.example.com\")\r\n```\r\n\r\n## Error Handling\r\n\r\nThe library raises specific exceptions for different error cases:\r\n\r\n```python\r\nfrom mcsrvstatus.exceptions import ServerNotFoundError, APIError, ConnectionError\r\n\r\ntry:\r\n status = client.get_server_status(\"nonexistent.server.com\")\r\nexcept ServerNotFoundError:\r\n print(\"Server is offline or doesn't exist\")\r\nexcept APIError as e:\r\n print(f\"API error: {e}\")\r\nexcept ConnectionError as e:\r\n print(f\"Network error: {e}\")\r\n```\r\n\r\n## Examples\r\n\r\n### Basic Server Information\r\n\r\n```python\r\nfrom mcsrvstatus import MinecraftServerStatus\r\n\r\nclient = MinecraftServerStatus()\r\n\r\nserver = \"mc.hypixel.net\"\r\n\r\ntry:\r\n # Basic info\r\n print(f\"Checking {server}...\")\r\n \r\n if client.is_server_online(server):\r\n status = client.get_server_status(server)\r\n print(f\"\u2713 Online: {status.players.online}/{status.players.max} players\")\r\n print(f\"\u2713 Version: {status.version.name}\")\r\n print(f\"\u2713 MOTD: {status.motd.text}\")\r\n else:\r\n print(\"\u2717 Server is offline\")\r\n\r\nfinally:\r\n client.close()\r\n```\r\n\r\n### Multiple Servers Check\r\n\r\n```python\r\nimport asyncio\r\nfrom mcsrvstatus import AsyncMinecraftServerStatus\r\n\r\nasync def check_servers():\r\n servers = [\r\n \"mc.hypixel.net\",\r\n \"play.mineplex.com\", \r\n \"hub.mcs.gg\"\r\n ]\r\n \r\n async with AsyncMinecraftServerStatus() as client:\r\n tasks = []\r\n for server in servers:\r\n task = asyncio.create_task(check_single_server(client, server))\r\n tasks.append(task)\r\n \r\n await asyncio.gather(*tasks)\r\n\r\nasync def check_single_server(client, server):\r\n try:\r\n if await client.is_server_online(server):\r\n status = await client.get_server_status(server)\r\n print(f\"{server}: {status.players.online}/{status.players.max} players\")\r\n else:\r\n print(f\"{server}: Offline\")\r\n except Exception as e:\r\n print(f\"{server}: Error - {e}\")\r\n\r\nasyncio.run(check_servers())\r\n```\r\n\r\n### Bedrock Server\r\n\r\n```python\r\nfrom mcsrvstatus import MinecraftServerStatus\r\n\r\nclient = MinecraftServerStatus()\r\n\r\ntry:\r\n status = client.get_bedrock_status(\"play.nethergames.org\")\r\n print(f\"Bedrock server online: {status.online}\")\r\n print(f\"Players: {status.players.online}/{status.players.max}\")\r\nexcept Exception as e:\r\n print(f\"Error: {e}\")\r\nfinally:\r\n client.close()\r\n```\r\n\r\n### Context Manager Usage\r\n\r\n```python\r\nfrom mcsrvstatus import MinecraftServerStatus\r\n\r\n# Automatically handles connection cleanup\r\nwith MinecraftServerStatus() as client:\r\n status = client.get_server_status(\"play.example.com\")\r\n print(f\"Server: {status.ip}:{status.port}\")\r\n```\r\n\r\n## API Versions\r\n\r\nThe mcsrvstat.us API supports versions 1, 2, and 3 (default). You can specify the version:\r\n\r\n```python\r\n# Use API version 2\r\nstatus = client.get_server_status(\"play.example.com\", version=2)\r\n```\r\n\r\n## Requirements\r\n\r\n- Python 3.6+\r\n- requests (for sync client)\r\n- aiohttp (for async client)\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for working with the mcsrvstat.us API - a service for checking the status of Minecraft servers",
"version": "1.0.6",
"project_urls": {
"Documentation": "https://github.com/Towux/mcsrvstatus#readme",
"Homepage": "https://github.com/Towux/mcsrvstatus",
"Issues": "https://github.com/Towux/mcsrvstatus/issues",
"Repository": "https://github.com/Towux/mcsrvstatus"
},
"split_keywords": [
"minecraft",
" server",
" status",
" api",
" mcsrvstat",
" bedrock",
" java",
" async"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6bbc1bf1ae3a9c442c458492627c20e2875786a725b8c82bf83e1a0d26ebae66",
"md5": "fd6ebf09922510291d584cc71b72a7f1",
"sha256": "d769b930009e568ce2416e0f960120ef4a2d0450602774b3ea8428cf03d71b24"
},
"downloads": -1,
"filename": "mcsrvstatus-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd6ebf09922510291d584cc71b72a7f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10483,
"upload_time": "2025-08-09T22:42:52",
"upload_time_iso_8601": "2025-08-09T22:42:52.666145Z",
"url": "https://files.pythonhosted.org/packages/6b/bc/1bf1ae3a9c442c458492627c20e2875786a725b8c82bf83e1a0d26ebae66/mcsrvstatus-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "752da0dffe13742033c9a08a1458bd27351b6d04ff31a42fdf69e1a203d3acb8",
"md5": "091463f167f6bf1b5539b7221e1aa087",
"sha256": "7f48b89a15713c61d559fb2a8ff7f068d216c7fabb5480e3bdf7a7746b877f41"
},
"downloads": -1,
"filename": "mcsrvstatus-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "091463f167f6bf1b5539b7221e1aa087",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11921,
"upload_time": "2025-08-09T22:42:53",
"upload_time_iso_8601": "2025-08-09T22:42:53.941854Z",
"url": "https://files.pythonhosted.org/packages/75/2d/a0dffe13742033c9a08a1458bd27351b6d04ff31a42fdf69e1a203d3acb8/mcsrvstatus-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 22:42:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Towux",
"github_project": "mcsrvstatus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.1"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
}
],
"lcname": "mcsrvstatus"
}
JSON
