| Name | mctools JSON |
| Version |
1.4.1
JSON |
| download |
| home_page | None |
| Summary | Python implementations of common Minecraft protocols. |
| upload_time | 2025-09-02 22:45:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.6 |
| license | MIT License
Copyright (c) 2020 Owen Cochell
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
minecraft
rcon
query
ping
server list ping
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Minecraft Connection Tools
A python implementation for interacting with Minecraft servers.
[](https://mctools.readthedocs.io/en/latest/?badge=latest)
# Introduction
mctools allows you to interact with Minecraft servers via [rcon](https://wiki.vg/RCON),
[query](https://wiki.vg/Query), and [server list ping protocol](https://wiki.vg/Server_List_Ping).
This allows you to do the following:
- Send and receive Minecraft server commands
- Get player count(max and currently playing)
- Get server version
- Get the message of the day
- Get currently installed plugins
- And much more!
All of this can be achieved using simple, intuitive calls to mctools. mctools does all the heavy lifting for you!
We offer synchronous and asynchronous components, allowing mctools to be used in asyncio event loops.
Also, mctools has no external dependencies(Unless you are a windows user and need color support),
and only uses the python standard library. Just download and go!
# Example
Send a command to the Minecraft server via rcon:
```python
from mctools import RCONClient # Import the RCONClient
HOST = 'mc.server.net' # Hostname of the Minecraft server
PORT = 1234 # Port number of the RCON server
# Create the RCONClient:
rcon = RCONClient(HOST, port=PORT)
# Login to RCON:
if rcon.login("password"):
# Send command to RCON - broadcast message to all players:
resp = rcon.command("broadcast Hello RCON!")
```
# Installation
You can install mctools via pip:
```bash
$ pip install mctools
```
If you are a windows user and want color support, then install mctools like so:
```bash
$ pip install mctools[color]
```
For more information on installing mctools, check out the instillation section in our
[documentation](https://mctools.readthedocs.io/en/latest/install.html).
# Formatting
mctools has support for handling Minecraft formatting codes.
You can decide weather mctools replaces formatting characters with intended values, removes them, or leaves them be.
For example, lets say you received the following content during a rcon session:
```
§e--------- §fHelp: Index (1/40) §e--------------------
§7Use /help [n] to get page n of help.
§6Aliases: §fLists command aliases
§6Bukkit: §fAll commands for Bukkit
§6ClearLag: §fAll commands for ClearLag
§6Essentials: §fAll commands for Essentials
§6LuckPerms: §fAll commands for LuckPerms
§6Minecraft: §fAll commands for Minecraft
§6Vault: §fAll commands for Vault
§6WorldEdit: §fAll commands for WorldEdit
```
As you can see, this text is somewhat hard to read. If you told mctools to remove the formatting characters,
then the output will look like this:
```
--------- Help: Index (1/40) --------------------
Use /help [n] to get page n of help.
Aliases: Lists command aliases
Bukkit: All commands for Bukkit
ClearLag: All commands for ClearLag
Essentials: All commands for Essentials
LuckPerms: All commands for LuckPerms
Minecraft: All commands for Minecraft
Vault: All commands for Vault
WorldEdit: All commands for WorldEdit
```
Much easier to read and process. mctools handles this operation automatically, so you don't have to.
mctools also handles situations where content is sent in ChatObject notation, and can extract messages from the
player sample list.
To learn more about formatters, and how to create your own,
then please check out the [formatting documentation](https://mctools.readthedocs.io/en/latest/format.html).
# MCLI - mctools Command Line Interface
mctools is shipped with a CLI front end called mcli, which you can use to start rcon sessions, get stats
via query/ping, check if a Minecraft server is up, ect.
After installing mctools(through pip or setuptools), you can invoke mcli like so:
```bash
$ mcli --help
```
You can also run mcli.py(which is located in the parent directory) if you downloaded the source code and did not
install via pip/setuptools.
The above command will generate the help menu for mcli. To learn more about mcli, please check out the
[mcli documentation](https://mctools.readthedocs.io/en/latest/mcli.html).
We supply mcli as an executable built using pyinstaller under releases
for windows systems that don't have python installed.
The exe file provided may be buggy or have some weird quirks,
so it is recommended to invoke mcli via python.
# Documentation
mctools has an extensive documentation. It contains tutorials, the API reference, and best practice recommendations.
You can find the [documentation here](https://mctools.readthedocs.io/).
Be sure to also check out the [mctools PyPi page](https://pypi.org/project/mctools/) for more information.
# Bug Reports
If you encounter a bug or any other event that does not seem normal,
then please open an issue, or email me personally.
I will be sure to get back to you as soon as possible.
Your feedback and reports are appreciated!
Your comments and issues are an excellent way to correct issues with mctools.
# Contributing
Pull requests are welcome and encouraged :) ! If you want to see a feature in mctools, or have found a bug,
a PR will be the quickest way to get your change implemented.
Feel free to email me or open an issue if you have any problems.
If you are interested in helping in the development of mctools, then send me an email, and we can get talking!
Believe me, there is plenty of work that needs to be done. More help would be greatly appreciated!
# Conclusion
mctools offers a pythonic, reliable way to interact with Minecraft servers, without being too complicated.
Please check the documentation for more information. More features (hopefully) coming soon!
Thank you for reading!
Raw data
{
"_id": null,
"home_page": null,
"name": "mctools",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "minecraft, rcon, query, ping, server list ping",
"author": null,
"author_email": "Owen Cochell <owencochell@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/04/00/ab0b4bc493b0112b38dfa06cc75959a683ebe5faffe6b27f8c26cc39b53b/mctools-1.4.1.tar.gz",
"platform": null,
"description": "# Minecraft Connection Tools\nA python implementation for interacting with Minecraft servers.\n\n[](https://mctools.readthedocs.io/en/latest/?badge=latest)\n\n# Introduction\n\nmctools allows you to interact with Minecraft servers via [rcon](https://wiki.vg/RCON), \n[query](https://wiki.vg/Query), and [server list ping protocol](https://wiki.vg/Server_List_Ping).\n\nThis allows you to do the following:\n\n- Send and receive Minecraft server commands\n- Get player count(max and currently playing)\n- Get server version\n- Get the message of the day\n- Get currently installed plugins\n- And much more!\n\nAll of this can be achieved using simple, intuitive calls to mctools. mctools does all the heavy lifting for you!\nWe offer synchronous and asynchronous components, allowing mctools to be used in asyncio event loops. \nAlso, mctools has no external dependencies(Unless you are a windows user and need color support),\nand only uses the python standard library. Just download and go!\n\n# Example\n\nSend a command to the Minecraft server via rcon:\n\n```python\nfrom mctools import RCONClient # Import the RCONClient\n\nHOST = 'mc.server.net' # Hostname of the Minecraft server\nPORT = 1234 # Port number of the RCON server\n\n# Create the RCONClient:\n\nrcon = RCONClient(HOST, port=PORT)\n\n# Login to RCON:\n\nif rcon.login(\"password\"):\n\n # Send command to RCON - broadcast message to all players:\n\n resp = rcon.command(\"broadcast Hello RCON!\")\n```\n\n# Installation \n\nYou can install mctools via pip:\n\n```bash\n$ pip install mctools\n```\n\nIf you are a windows user and want color support, then install mctools like so:\n\n```bash\n$ pip install mctools[color]\n```\n\nFor more information on installing mctools, check out the instillation section in our \n[documentation](https://mctools.readthedocs.io/en/latest/install.html).\n\n# Formatting\n\nmctools has support for handling Minecraft formatting codes. \nYou can decide weather mctools replaces formatting characters with intended values, removes them, or leaves them be.\n\nFor example, lets say you received the following content during a rcon session:\n\n```\n\u00a7e--------- \u00a7fHelp: Index (1/40) \u00a7e--------------------\n\u00a77Use /help [n] to get page n of help.\n\u00a76Aliases: \u00a7fLists command aliases\n\u00a76Bukkit: \u00a7fAll commands for Bukkit\n\u00a76ClearLag: \u00a7fAll commands for ClearLag\n\u00a76Essentials: \u00a7fAll commands for Essentials\n\u00a76LuckPerms: \u00a7fAll commands for LuckPerms\n\u00a76Minecraft: \u00a7fAll commands for Minecraft\n\u00a76Vault: \u00a7fAll commands for Vault\n\u00a76WorldEdit: \u00a7fAll commands for WorldEdit\n```\n\nAs you can see, this text is somewhat hard to read. If you told mctools to remove the formatting characters,\nthen the output will look like this:\n\n```\n--------- Help: Index (1/40) --------------------\nUse /help [n] to get page n of help.\nAliases: Lists command aliases\nBukkit: All commands for Bukkit\nClearLag: All commands for ClearLag\nEssentials: All commands for Essentials\nLuckPerms: All commands for LuckPerms\nMinecraft: All commands for Minecraft\nVault: All commands for Vault\nWorldEdit: All commands for WorldEdit\n```\n\nMuch easier to read and process. mctools handles this operation automatically, so you don't have to.\nmctools also handles situations where content is sent in ChatObject notation, and can extract messages from the\nplayer sample list.\n\nTo learn more about formatters, and how to create your own,\nthen please check out the [formatting documentation](https://mctools.readthedocs.io/en/latest/format.html).\n\n# MCLI - mctools Command Line Interface\n\nmctools is shipped with a CLI front end called mcli, which you can use to start rcon sessions, get stats\nvia query/ping, check if a Minecraft server is up, ect.\n\nAfter installing mctools(through pip or setuptools), you can invoke mcli like so:\n\n```bash\n$ mcli --help\n```\n\nYou can also run mcli.py(which is located in the parent directory) if you downloaded the source code and did not\ninstall via pip/setuptools.\n\nThe above command will generate the help menu for mcli. To learn more about mcli, please check out the \n[mcli documentation](https://mctools.readthedocs.io/en/latest/mcli.html).\n\nWe supply mcli as an executable built using pyinstaller under releases\nfor windows systems that don't have python installed.\nThe exe file provided may be buggy or have some weird quirks,\nso it is recommended to invoke mcli via python.\n\n# Documentation\n\nmctools has an extensive documentation. It contains tutorials, the API reference, and best practice recommendations.\nYou can find the [documentation here](https://mctools.readthedocs.io/).\n\nBe sure to also check out the [mctools PyPi page](https://pypi.org/project/mctools/) for more information.\n\n# Bug Reports\n\nIf you encounter a bug or any other event that does not seem normal,\nthen please open an issue, or email me personally.\nI will be sure to get back to you as soon as possible.\n\nYour feedback and reports are appreciated!\nYour comments and issues are an excellent way to correct issues with mctools.\n\n# Contributing\n\nPull requests are welcome and encouraged :) ! If you want to see a feature in mctools, or have found a bug,\na PR will be the quickest way to get your change implemented. \nFeel free to email me or open an issue if you have any problems.\n\nIf you are interested in helping in the development of mctools, then send me an email, and we can get talking!\nBelieve me, there is plenty of work that needs to be done. More help would be greatly appreciated!\n\n# Conclusion\n\nmctools offers a pythonic, reliable way to interact with Minecraft servers, without being too complicated.\nPlease check the documentation for more information. More features (hopefully) coming soon!\n\nThank you for reading!\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2020 Owen Cochell\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Python implementations of common Minecraft protocols.",
"version": "1.4.1",
"project_urls": {
"Documentation": "https://mctools.readthedocs.io/",
"Issues": "https://github.com/Owen-Cochell/mctools/issues",
"Repository": "https://github.com/Owen-Cochell/mctools"
},
"split_keywords": [
"minecraft",
" rcon",
" query",
" ping",
" server list ping"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9a2fbc156a791c0c651629695e6191d42a5a2b85000195da052a4e9c7bbc1f5c",
"md5": "03400057476f404cb5d2543514114160",
"sha256": "c381f69c78effa490512b7515be3461252886d1a66981b94d53a4c718584d3bb"
},
"downloads": -1,
"filename": "mctools-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "03400057476f404cb5d2543514114160",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 43942,
"upload_time": "2025-09-02T22:45:13",
"upload_time_iso_8601": "2025-09-02T22:45:13.939250Z",
"url": "https://files.pythonhosted.org/packages/9a/2f/bc156a791c0c651629695e6191d42a5a2b85000195da052a4e9c7bbc1f5c/mctools-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0400ab0b4bc493b0112b38dfa06cc75959a683ebe5faffe6b27f8c26cc39b53b",
"md5": "78a7f6320b771daca331c5c5b8d69d12",
"sha256": "5b8d2877586d3e8ee75cc8ec5a2280400e1ab089379c7aa9de2e0c7d290d7efc"
},
"downloads": -1,
"filename": "mctools-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "78a7f6320b771daca331c5c5b8d69d12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 41501,
"upload_time": "2025-09-02T22:45:15",
"upload_time_iso_8601": "2025-09-02T22:45:15.346188Z",
"url": "https://files.pythonhosted.org/packages/04/00/ab0b4bc493b0112b38dfa06cc75959a683ebe5faffe6b27f8c26cc39b53b/mctools-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 22:45:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Owen-Cochell",
"github_project": "mctools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mctools"
}
