WhitelistCleanup - Automatic Whitelist Maintenance
Keep your Minecraft server whitelist tidy and up-to-date — automatically!

WhitelistCleanup is a lightweight utility plugin for Spigot and Paper servers that scans your whitelist on startup or command and removes players who haven't logged in within a configurable number of days. It also keeps a safe backup of all removed entries so you can restore them if needed.

✅ Features

• Automatic cleanup on server startup
  
  
• Manual cleanup via /whitelist cleanup command
  
  
• Removes players inactive for X days (configurable)
  
  
• Optionally remove players who have never joined
• Saves removed players to removals.json in the same format as whitelist.json
  
  
• Exclude specific players by username or UUID
  
  
• ️ Exclude players based on Vault permission groups (e.g., Admins, Moderators)
  
  
• ️ Optional broadcast to ops with summary after cleanup
  
  
• Highly configurable via config.yml

Installation

1. Download the plugin JAR and drop it into your /plugins folder.
   
2. Restart or reload your server.
   
3. Configure the config.yml to your needs.
   
4. Done!

Configuration


Commands
/whitelist cleanup - Manually trigger the whitelist cleanup

Requirements

• Java 17+
  
• Spigot, Paper, or forked servers
  
• (Optional) Vault + a supported permissions plugin for rank-based exclusions

Permissions

• whitelist.cleanup — Allows manual execution of the cleanup command