MCS — Minecraft Server Scanner

Scan and auto-stop inactive Minecraft servers on Pterodactyl.

How it works

1. Lists all servers from the Pterodactyl panel via the Application API
2. Filters Minecraft servers (Nest 19 / Eggs 59, 60, 61)
3. Pings each Minecraft server to get real-time player count
4. Stops servers that have been empty for over 48h

Project abandoned

This project was cancelled due to excessive Pterodactyl API restrictions.

Issues encountered:

• The Application API cannot stop a server — only suspend (lock) is available
• The Client API requires an admin token with "Allow access to all servers" to stop a server
• The power and command endpoints return 404 if the token doesn't have access to the server (security through obscurity)
• Stop functionality via the Application API was rejected by Pterodactyl (issue #4321)

Result: a simple detection + stop script becomes a nightmare of authentication and permissions.

Requirements

• Node.js 18+
• A Pterodactyl panel with API access
• An Application API key (Admin > Application API)
• (Optional) An admin Client API key with access to all servers

Setup

git clone https://github.com/ZeroHost-Code/MCS.git
cd MCS
cp .env.example .env
# edit .env with your credentials
npm install

Usage

# Detection + stop
npm start

# Simulation (does nothing)
npm run dry-run

Take over

This project is not under the ZeroHost Source License (ZHSL) or any other license. You may fork, modify, sell, or do whatever you want with it.

What's left to do / improve:

• Replace the Client API with direct Wings API calls (POST /api/servers/{uuid}/power)
• Multi-node support
• Web interface
• Notifications (Discord, Slack, etc.)