Skip to content

README.md

Latest commit

 

History

History
99 lines (73 loc) · 2.77 KB

README.md

File metadata and controls

99 lines (73 loc) · 2.77 KB
Raw

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