Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/py-mine/mcstatus
A Python library for checking the status of Minecraft servers
https://github.com/py-mine/mcstatus
minecraft python
Last synced: 5 days ago
JSON representation
A Python library for checking the status of Minecraft servers
- Host: GitHub
- URL: https://github.com/py-mine/mcstatus
- Owner: py-mine
- License: apache-2.0
- Created: 2022-02-15T00:07:53.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-11-08T18:33:03.000Z (8 days ago)
- Last Synced: 2024-11-08T19:28:43.988Z (8 days ago)
- Topics: minecraft, python
- Language: Python
- Homepage: https://mcstatus.readthedocs.io
- Size: 2.38 MB
- Stars: 479
- Watchers: 4
- Forks: 37
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 
MCStatus
[](https://discord.gg/C2wX7zduxC)
[](https://pypi.org/project/mcstatus/)
[](https://mcstatus.readthedocs.io/)
[](https://github.com/py-mine/mcstatus/actions/workflows/validation.yml)
[](https://github.com/py-mine/mcstatus/actions/workflows/tox-test.yml)
Mcstatus provides an API and command line script to fetch publicly available data from Minecraft servers. Specifically, mcstatus retrieves data by using these protocols: [Server List Ping](https://wiki.vg/Server_List_Ping) and [Query](https://wiki.vg/Query). Because of mcstatus, you do not need to fully understand those protocols and can instead skip straight to retrieving minecraft server data quickly in your own programs.
## Installation
Mcstatus is available on [PyPI](https://pypi.org/project/mcstatus/), and can be installed trivially with:
```bash
python3 -m pip install mcstatus
```
## Usage
### Python API
#### Java Edition
```python
from mcstatus import JavaServer
# You can pass the same address you'd enter into the address field in minecraft into the 'lookup' function
# If you know the host and port, you may skip this and use JavaServer("example.org", 1234)
server = JavaServer.lookup("example.org:1234")
# 'status' is supported by all Minecraft servers that are version 1.7 or higher.
# Don't expect the player list to always be complete, because many servers run
# plugins that hide this information or limit the number of players returned or even
# alter this list to contain fake players for purposes of having a custom message here.
status = server.status()
print(f"The server has {status.players.online} player(s) online and replied in {status.latency} ms")
# 'ping' is supported by all Minecraft servers that are version 1.7 or higher.
# It is included in a 'status' call, but is also exposed separate if you do not require the additional info.
latency = server.ping()
print(f"The server replied in {latency} ms")
# 'query' has to be enabled in a server's server.properties file!
# It may give more information than a ping, such as a full player list or mod information.
query = server.query()
print(f"The server has the following players online: {', '.join(query.players.names)}")
```
#### Bedrock Edition
```python
from mcstatus import BedrockServer
# You can pass the same address you'd enter into the address field in minecraft into the 'lookup' function
# If you know the host and port, you may skip this and use BedrockServer("example.org", 19132)
server = BedrockServer.lookup("example.org:19132")
# 'status' is the only feature that is supported by Bedrock at this time.
# In this case status includes players.online, latency, motd, map, gamemode, and players.max. (ex: status.gamemode)
status = server.status()
print(f"The server has {status.players.online} players online and replied in {status.latency} ms")
```
See the [documentation](https://mcstatus.readthedocs.io) to find what you can do with our library!
### Command Line Interface
The mcstatus library includes a simple CLI. Once installed, it can be used through:
```bash
python3 -m mcstatus --help
```
## License
Mcstatus is licensed under the Apache 2.0 license. See LICENSE for full text.