CleanMCA

What this tool does

CleanMCA is a command-line cleanup tool for server administrators. It reads an MCA filename whitelist and removes regular files whose names are not listed from the selected save’s region, poi, and entities directories. It does not inspect chunk contents or decide whether a file appears safe to remove; the whitelist is the retention boundary.

The repository provides a Bash script, a Python implementation, and a Windows batch entry point. For production servers, prefer the Python implementation: it is cross-platform, handles UTF-8 paths and filenames, and actually waits for y, yes, or 是 before deleting.

Read this before using it

• This is a deletion tool. It has no recycle bin, undo operation, or built-in recovery.
• Stop the server and back up the whole world before running it. At minimum, be able to restore region, poi, and entities; a complete world backup is safer.
• The --region / -r argument must point to a dimension’s region directory, not the world root. The tool looks for sibling poi and entities directories one level above it.
• The same whitelist is applied to all three directories. A filename not listed can be removed from the corresponding directory; the tool does not limit deletion to files ending in .mca.
• In the current master Bash script, the confirmation prompt is displayed but its response is not checked before processing continues. Typing n may therefore still continue. Prefer the Python implementation for production work, and treat Bash as a compatibility entry point only after verifying the target and backup.

Suggested reading order

Task	Start here
Set up the tool for the first time	Installation and runtime
Write or review the retention list	Whitelist files
Run and verify one cleanup	Using CleanMCA
Run it on Windows, Linux, macOS, or WSL	Platform and entry-point differences
Plan backups, shutdown, and recovery	Safety and recovery
Diagnose a failed run or world issue	Troubleshooting

Documentation baseline

This documentation is based on the current master-branch CleanMCA.sh, CleanMCA.py, CleanMCA.bat, README_python.md, and whitelist_example.txt. The repository’s latest recorded commit is dated 2025-07-17. The scripts may change; during an operation, treat the current repository files, terminal output, and backup state as authoritative.