| Name | mcstatus JSON |
| Version |
12.0.4
JSON |
| download |
| home_page | None |
| Summary | A library to query Minecraft Servers for their status and capabilities. |
| upload_time | 2025-08-13 17:06:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
minecraft
protocol
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# <img src="https://i.imgur.com/nPCcxts.png" height="25" style="height: 25px"> 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/unit-tests.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://minecraft.wiki/w/Java_Edition_protocol/Server_List_Ping) and [Query](https://minecraft.wiki/w/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.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcstatus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Kevin Tindall <kevinkjt2000@gmail.com>, ItsDrike <itsdrike@protonmail.com>, PerchunPak <perchunpak@gmail.com>",
"keywords": "minecraft, protocol",
"author": null,
"author_email": "Nathan Adams <dinnerbone@dinnerbone.com>, ItsDrike <itsdrike@protonmail.com>, PerchunPak <perchunpak@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/ec/1fdd2dfb1133b92c2194310eae23bc360d10f832d6c2b7e346936c93d9fd/mcstatus-12.0.4.tar.gz",
"platform": null,
"description": "# <img src=\"https://i.imgur.com/nPCcxts.png\" height=\"25\" style=\"height: 25px\"> MCStatus\n\n[](https://discord.gg/C2wX7zduxC)\n\n[](https://pypi.org/project/mcstatus/)\n[](https://mcstatus.readthedocs.io/)\n[](https://github.com/py-mine/mcstatus/actions/workflows/validation.yml)\n[](https://github.com/py-mine/mcstatus/actions/workflows/unit-tests.yml)\n\nMcstatus 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://minecraft.wiki/w/Java_Edition_protocol/Server_List_Ping) and [Query](https://minecraft.wiki/w/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.\n\n## Installation\n\nMcstatus is available on [PyPI](https://pypi.org/project/mcstatus/), and can be installed trivially with:\n\n```bash\npython3 -m pip install mcstatus\n```\n\n## Usage\n\n### Python API\n\n#### Java Edition\n\n```python\nfrom mcstatus import JavaServer\n\n# You can pass the same address you'd enter into the address field in minecraft into the 'lookup' function\n# If you know the host and port, you may skip this and use JavaServer(\"example.org\", 1234)\nserver = JavaServer.lookup(\"example.org:1234\")\n\n# 'status' is supported by all Minecraft servers that are version 1.7 or higher.\n# Don't expect the player list to always be complete, because many servers run\n# plugins that hide this information or limit the number of players returned or even\n# alter this list to contain fake players for purposes of having a custom message here.\nstatus = server.status()\nprint(f\"The server has {status.players.online} player(s) online and replied in {status.latency} ms\")\n\n# 'ping' is supported by all Minecraft servers that are version 1.7 or higher.\n# It is included in a 'status' call, but is also exposed separate if you do not require the additional info.\nlatency = server.ping()\nprint(f\"The server replied in {latency} ms\")\n\n# 'query' has to be enabled in a server's server.properties file!\n# It may give more information than a ping, such as a full player list or mod information.\nquery = server.query()\nprint(f\"The server has the following players online: {', '.join(query.players.names)}\")\n```\n\n#### Bedrock Edition\n\n```python\nfrom mcstatus import BedrockServer\n\n# You can pass the same address you'd enter into the address field in minecraft into the 'lookup' function\n# If you know the host and port, you may skip this and use BedrockServer(\"example.org\", 19132)\nserver = BedrockServer.lookup(\"example.org:19132\")\n\n# 'status' is the only feature that is supported by Bedrock at this time.\n# In this case status includes players.online, latency, motd, map, gamemode, and players.max. (ex: status.gamemode)\nstatus = server.status()\nprint(f\"The server has {status.players.online} players online and replied in {status.latency} ms\")\n```\n\nSee the [documentation](https://mcstatus.readthedocs.io) to find what you can do with our library!\n\n### Command Line Interface\n\nThe mcstatus library includes a simple CLI. Once installed, it can be used through:\n\n```bash\npython3 -m mcstatus --help\n```\n\n## License\n\nMcstatus is licensed under the Apache 2.0 license. See LICENSE for full text.\n",
"bugtrack_url": null,
"license": null,
"summary": "A library to query Minecraft Servers for their status and capabilities.",
"version": "12.0.4",
"project_urls": {
"Documentation": "https://mcstatus.readthedocs.io",
"Source code": "https://github.com/py-mine/mcstatus"
},
"split_keywords": [
"minecraft",
" protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f5e0c27e5342a6a2267167427bd8f014fd7e15091adede4eccdc7459ad2c18f9",
"md5": "020648f9e625a0c7da3b990f482efd9f",
"sha256": "adde9f0855820054ca24b6ef1bdde7c1000b501a35c65fccea0d5532fd3c3989"
},
"downloads": -1,
"filename": "mcstatus-12.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "020648f9e625a0c7da3b990f482efd9f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 43398,
"upload_time": "2025-08-13T17:06:08",
"upload_time_iso_8601": "2025-08-13T17:06:08.122743Z",
"url": "https://files.pythonhosted.org/packages/f5/e0/c27e5342a6a2267167427bd8f014fd7e15091adede4eccdc7459ad2c18f9/mcstatus-12.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e5ec1fdd2dfb1133b92c2194310eae23bc360d10f832d6c2b7e346936c93d9fd",
"md5": "181c337a5a62b2375058de8e575c392f",
"sha256": "5b07b0391272ceef31996e42d3534456af921a160023b82fc0da59c4198b3059"
},
"downloads": -1,
"filename": "mcstatus-12.0.4.tar.gz",
"has_sig": false,
"md5_digest": "181c337a5a62b2375058de8e575c392f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 134687,
"upload_time": "2025-08-13T17:06:09",
"upload_time_iso_8601": "2025-08-13T17:06:09.730802Z",
"url": "https://files.pythonhosted.org/packages/e5/ec/1fdd2dfb1133b92c2194310eae23bc360d10f832d6c2b7e346936c93d9fd/mcstatus-12.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 17:06:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "py-mine",
"github_project": "mcstatus",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "mcstatus"
}
