https://github.com/alexitx/mc-status-webhook
Minecraft server status webhook for Discord
https://github.com/alexitx/mc-status-webhook
command-line discord discord-webhook logging minecraft minecraft-server monitoring python status utility webhook
Last synced: 2 months ago
JSON representation
Minecraft server status webhook for Discord
- Host: GitHub
- URL: https://github.com/alexitx/mc-status-webhook
- Owner: alexitx
- License: mit
- Created: 2021-12-07T23:08:11.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-03-04T16:39:50.000Z (over 4 years ago)
- Last Synced: 2025-09-24T05:28:35.351Z (9 months ago)
- Topics: command-line, discord, discord-webhook, logging, minecraft, minecraft-server, monitoring, python, status, utility, webhook
- Language: Python
- Homepage:
- Size: 27.3 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Minecraft server status webhook for Discord
Poll a server and send customizable webhook embed if the status changes.
Requires Python 3.7+
## Table of contents
- [Installation](#installation)
- [Usage](#usage)
- [CLI arguments](#cli-arguments)
- [Environment variables](#environment-variables)
- [License](#license)
## Installation
###### Use `python` on Windows instead of `python3`
Update pip and dependencies
```sh
$ python3 -m pip install --upgrade pip
$ python3 -m pip install --upgrade setuptools wheel
```
Install
```sh
$ python3 -m pip install --upgrade mc-status-webhook
```
## Usage
```sh
$ python3 mc_status_webhook.py -u "" [options]
```
or set the appropriate environment variables.
See [CLI arguments](#cli-arguments) and [Environment variables](#environment-variables)
for configuration.
Example scripts are also provided in the 'examples' directory.
Get [msw-example.cmd][windows-script] for Windows or [msw-example.sh][linux-script]
for Linux and modify it to your needs.
> **Note 1:** It is strongly recommended to run mc-status-webhook on the same machine or local
> network as the Minecraft server to avoid false notifications due to connection issues and wasting
> bandwidth. In this case use the loopback address 127.0.0.1 or the local address of the machine.
> **Note 2:** When working with BungeeCord-based proxies, use `-s` or `--full-status` to request
> full status information, because BungeeCord does not respond to just ping. Note that this will
> fetch more data such as MOTD, icon, version, sample players and will use more bandwidth if the
> update time is set too low.
### CLI arguments
| Argument | Type | Default | Required | Description |
|------------------------|-------|-----------------|----------|---------------------------------------------------------------------------------|
| -H, --host | str | 127.0.0.1 | No | Server address |
| -p, --port | int | 25565 | No | Server port |
| -t, --update-time | float | 10.0 | No | Time in seconds between checking the server status |
| -i, --initial-status | bool | | No | Send a webhook with the server status on application start |
| -s, --full-status | bool | | No | Request full status info instead of just pinging (for BungeeCord-based proxies) |
| -u, --webhook-url | str | | Yes | Discord webhook URL |
| -d, --debug | bool | | No | Log debug messages |
| --online-color | str | 30c030 | No | Webhook color hex when the server is online |
| --offline-color | str | ff4040 | No | Webhook color hex when the server is offline |
| --online-thumb-url | str | \ | No | Webhook thumbnail URL when the server is online ('none' = disabled) |
| --offline-thumb-url | str | \ | No | Webhook thumbnail URL when the server is offline ('none' = disabled) |
| --status-title | str | Status | No | Webhook status title |
| --status-online-value | str | Online | No | Webhook status value when the server is online |
| --status-offline-value | str | Offline | No | Webhook status value when the server is offline |
| --address-title | str | Address | No | Webhook address title |
| --address-value | str | | No | Webhook address value when the server is online |
### Environment variables
| Environment variable | Equivalent argument |
|--------------------------|-------------------------|
| MSW_HOST | -H, --host |
| MSW_PORT | -p, --port |
| MSW_WEBHOOK_URL | -u, --webhook-url |
| MSW_ONLINE_COLOR | --online-color |
| MSW_OFFLINE_COLOR | --offline-color |
| MSW_ONLINE_THUMB_URL | --online-thumbnail-url |
| MSW_OFFLINE_THUMB_URL | --offline-thumbnail-url |
| MSW_STATUS_TITLE | --status-title |
| MSW_STATUS_ONLINE_VALUE | --status-online-value |
| MSW_STATUS_OFFLINE_VALUE | --status-offline-value |
| MSW_ADDRESS_TITLE | --address-title |
| MSW_ADDRESS_VALUE | --address-value |
## License
MIT license. See [LICENSE][license] for more information.
[windows-script]: https://github.com/alexitx/mc-status-webhook/raw/master/examples/msw-example.cmd
[linux-script]: https://github.com/alexitx/mc-status-webhook/raw/master/examples/msw-example.sh
[license]: https://github.com/alexitx/mc-status-webhook/blob/master/LICENSE