Minecraft Server Monitor Bot

Discord bot that monitors a Minecraft Java server and updates a voice channel name with the current player count.

🔊 Voice Channel: "Online: 12/50"  ← Updates automatically

Features

• Auto-updating channel name: Shows Online: X/Max or custom prefix
• Configurable interval: Default 90s (respects Discord rate limits)
• Clean async architecture: Uses discord.py tasks
• Environment-based config: No hardcoded secrets
• Interactive first-run setup: Creates config.ini if missing
• Graceful error handling: Logs errors, continues running

Requirements

• Python 3.10+
• Discord bot with Manage Channels permission
• Minecraft Java server with query enabled (or standard ping)

Quick Start

# 1. Clone
git clone <repo>
cd Minecraft-Server-Monitor

# 2. Install deps
pip install -r requirements.txt

# 3. Configure
cp .env.example .env
# Edit .env with your values

# 4. Run
python -m src.main

Configuration (.env)

Variable	Required	Description
DISCORD_TOKEN	✅	Bot token from Discord Developer Portal
MC_SERVER_ADDRESS	✅	Minecraft server IP/hostname
MC_SERVER_PORT	✅	Server port (default 25565)
DISCORD_CHANNEL_ID	✅	Voice channel ID to rename
DISCORD_GUILD_ID	✅	Discord server (guild) ID
CHANNEL_DISPLAY_NAME	❌	Prefix text (default: "Online")
UPDATE_RATE	❌	Seconds between updates (min 90 recommended)

Getting Channel/Guild IDs

1. Enable Developer Mode in Discord (Settings → Advanced)
2. Right-click server → Copy Server ID = DISCORD_GUILD_ID
3. Right-click voice channel → Copy Channel ID = DISCORD_CHANNEL_ID

Project Structure

Minecraft-Server-Monitor/
├── src/
│   └── main.py        # Bot entry point
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md

How It Works

1. JavaServer.lookup() from mcstatus pings the server
2. status.players.online / .max gives current/max players
3. Background task (@tasks.loop) runs every UPDATE_RATE seconds
4. Updates voice channel name via channel.edit(name="...")

Rate Limits

Discord limits channel edits. Keep UPDATE_RATE ≥ 90 to avoid 429 errors. The bot warns if you set it lower.

Troubleshooting

Issue	Fix
"Guild/Channel not found"	Check IDs, ensure bot is in server
"Invalid token"	Regenerate token in Developer Portal
"Connection refused"	Check server IP/port, firewall
429 Too Many Requests	Increase UPDATE_RATE to 120+
Config not saving	Run with write permissions

License

MIT — use freely, attribution appreciated.

---

Originally created ~2023, modernized 2025