Minecraft Server Watcher

A Python script that polls one or more Minecraft servers and sends you an email via Resend when a server goes down or comes back online.

How it works

Every 60 seconds (configurable), the script pings your server using the same protocol Minecraft uses in the server list. If the server stops responding, you get an email. When it comes back up, you get another email showing how long it was down, the current player count, and the server version.

Setup

1. Clone the repo

git clone https://github.com/arnavtejasvi/server-watcher.git
cd server-watcher

2. Install dependencies

pip3 install -r requirements.txt

3. Create your config

Copy the example config and fill it in:

cp config.example.json config.json

Open config.json and set:

Field	Description
resend_api_key	Your Resend API key — sign up free at resend.com, go to API Keys → Create API Key
to_email	The email address to send alerts to
servers	List of servers to watch (see below)
poll_interval_seconds	How often to check — default is 60

Adding your server:

{
  "resend_api_key": "re_yourKeyHere",
  "to_email": "you@example.com",
  "servers": [
    {
      "name": "My Server",
      "host": "play.yourserver.com",
      "port": 25565
    }
  ],
  "poll_interval_seconds": 60
}

You can watch multiple servers at once — just add more entries to the servers list:

"servers": [
  { "name": "Survival",  "host": "play.yourserver.com", "port": 25565 },
  { "name": "Creative",  "host": "play.yourserver.com", "port": 25566 }
]

The port field is optional and defaults to 25565.

4. Test your setup

Send a test email to make sure everything is connected:

python3 watch.py --test

5. Run it

Daemon mode — runs forever, polls on the configured interval:

python3 watch.py

One-shot mode — checks once and exits (useful for cron):

python3 watch.py --once

Running automatically

macOS / Linux (cron)

Run a check every minute via cron:

crontab -e

Add this line (update the path to match where you cloned the repo):

* * * * * /usr/bin/python3 /path/to/server-watcher/watch.py --once >> /path/to/server-watcher/watcher.log 2>&1

Keep it running with nohup

nohup python3 watch.py > watcher.log 2>&1 &

Emails

When a server goes down:

🔴 My Server is offline

When it comes back up:

🟢 My Server is back online — was down for 14m, 3/20 players online

Notes

• config.json and state.json are gitignored — your API key and server details stay local.
• The script uses the Minecraft Server List Ping protocol, so it correctly detects when a server process has crashed even if the port is still technically open.