Minecraft Server Monitor

A system to monitor player counts on multiple Minecraft servers and generate graphs.

Setup

1. Install dependencies:

pip install -r requirements.txt

2. Configure environment variables in .env:

DATABASE_URL=postgresql://username:password@localhost/minecraft_monitor
# Or for SQLite: DATABASE_URL=sqlite:///./minecraft_monitor.db

3. Initialize the database:

cd src
alembic init alembic
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head

4. Set up the cron job for the scraper:

crontab -e
# Add this line:
*/15 * * * * cd /path/to/project && /usr/bin/python3 src/scraper.py >> /var/log/minecraft_scraper.log 2>&1

5. Create your servers.json file:

[
  {
    "id": "mce",
    "name": "MC Eternal",
    "ip": "calmingstorm.net",
    "port": 25580
  },
  {
    "id": "gtnh",
    "name": "GregTech: New Horizons",
    "ip": "calmingstorm.net",
    "port": 25567
  }
]

6. Run the API server:

cd src
python api.py
# Or with uvicorn:
uvicorn api:app --host 0.0.0.0 --port 8000 --reload

API Endpoints

• GET / - API root
• GET /servers - List all monitored servers
• GET /graph/{server_id}?period={days} - Generate player count graph (HTML page)
• GET /graph/{server_id}/image?period={days} - Get player count graph as PNG image
• GET /stats/{server_id}?period={days} - Get server statistics

Parameters

• server_id - The unique identifier for the server (from servers.json)
• period - Number of days to display (1-365, default: 7)

Directory Structure

minecraft-server-monitor/
├── .env
├── requirements.txt
├── servers.json
├── README.md
├── alembic.ini
├── templates/
│   └── graph.html
├── alembic/
│   ├── env.py
│   └── script.py.mako
└── src/
    ├── __init__.py
    ├── scraper.py
    ├── api.py
    └── models/
        ├── __init__.py
        ├── database.py
        └── models.py