Launch, operate, and package Minecraft Server Finder with confidence.

Clone and install

Use these commands exactly as they appear in README.md.

git clone https://github.com/braydos-h/Minecraft-Server-Finder.git
cd Minecraft-Server-Finder
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Optional enrichment

Install extras to unlock deeper signal analysis:

• pip install mcstatus for richer MOTDs and protocol data.
• pip install python-nmap to corroborate service banners.
• pip install psutil to augment GUI system metrics.
• Install Mullvad’s CLI/SDK if you plan to rotate VPN exits automatically.

Know the CLI switches

Only supported flags are listed below.

• python app.py — launch the Tkinter interface.
• python app.py --nogui — force console mode even if Tkinter is available.
• python app.py -h — print the current help text.

Core controls

• Set start/end IPs or CIDR ranges in the address controls.
• Adjust the worker slider (default 150 threads) and TCP timeout (default 4 seconds).
• Provide additional ports for Bedrock or modded servers if needed.

Proxy pool management

• Edit mcsmartscan/mullvadproxyips.txt before launching to seed proxies.
• Use the GUI Proxy Pool panel to monitor health, lease counts, and cooldown timers.
• Toggle Mullvad cycling only if the Mullvad app/CLI is online and authenticated.

Results & exports

• Watch the live table and log pane for MOTDs, latency bars, and status cues.
• Change the output path if you prefer a shared folder or external drive.
• Export confirmed servers or open port leads directly from the UI at any time.

Start a headless session

python app.py --nogui

• The shim exposes state such as processed hosts, latency averages, and failure ratios.
• Define run_console_scan(app), console_scan_loop(app), or similar helpers in app.py to automate workflows.

Schedule with cron or Task Scheduler

• Activate the virtual environment before launching the script.
• Use environment variables or code edits to change ranges per run.
• Review StorageManager outputs after each scheduled sweep.

Logging best practices

• Redirect stdout/stderr to files for long sessions: python app.py --nogui > scan.log 2>&1.
• Rotate logs regularly to prevent large files on disk.
• Keep the ethical guidelines in mind when running unattended scans.

Local PyInstaller build

Set-ExecutionPolicy -Scope Process Bypass
./pyinstaller.ps1

• Produces dist/MinecraftServerFinder.exe using the maintained spec file.
• Includes proxy lists and the mcsmartscan package by default.
• Matches the behaviour of the GitHub Actions packaging workflow.

GitHub Actions release

• Trigger the Build Windows Release workflow manually or by tagging a commit with v*.
• CI runs on windows-latest and uploads the packaged executable as a release asset.
• Combine with the Python application workflow for automated tests on Windows, macOS, and Linux.

Bootstrap Windows machines

install_system.bat

• Installs Python dependencies system-wide and upgrades pip.
• Ideal for lab or classroom deployments where virtualenvs are inconvenient.
• Add optional extras afterwards if you need deeper protocol insight.

Run tests locally

pytest

• Exercises utilities and storage helpers under tests/.
• Add new tests alongside code changes to keep coverage meaningful.

Lint before committing

flake8 .

• Aligns with the Python application workflow executed in CI.
• Combine with your preferred formatters (black, ruff, mypy) if you want stricter local checks.

Document behaviour updates

• Update README.md, this usage page, and the feature overview when functionality changes.
• Note new CLI switches or GUI controls explicitly so operators are never surprised.
• Coordinate with the ethics guidance whenever throughput or automation features shift.