Feature overview

Capabilities built for high-signal Minecraft reconnaissance.

Every component is documented and shipped in-repo: from the ThreadPoolExecutor-driven scan loop to the proxy pool, Mullvad integration, Tkinter UI, and persistence layer.

Download from GitHub Read usage guides
Engine core

Reliable coverage across massive IPv4 ranges.

The scanning engine lives in mcsmartscan and is reused by both the GUI and headless entry points.

Threaded scan loops

The engine balances sockets, CPU, and file writes so long sweeps stay responsive.

  • ThreadPoolExecutor workers consume a bounded queue fed by ip_range_generator.
  • permuted_index_generator shuffles targets deterministically to avoid hotspots while guaranteeing coverage.
  • DEFAULT_WORKERS = 150 (tune from the GUI or programmatically before launching).

Proxy and VPN aware

ProxyPool manages SOCKS5 endpoints so you can distribute traffic or rotate egress IPs.

  • Maintain endpoints in mcsmartscan/mullvadproxyips.txt (one per line, comments allowed).
  • Cooldown timers quarantine unhealthy proxies and retry on a back-off curve.
  • Optional MullvadManager hooks into Mullvad’s CLI/SDK for automated exit rotation.

Protocol enrichment

Hosts that pass TCP validation receive Minecraft-specific parsing before being classified.

  • Java status handshakes capture protocol version hints, MOTDs, latency, and player counts.
  • mcstatus (optional) unlocks extended parsing for modern servers.
  • python-nmap integration (optional) corroborates suspicious responses with banner data.
Operator experience

Work visually or run in fully headless environments.

The UI and console flows ride on the same orchestrator so switching contexts is seamless.

Tkinter GUI

Launch with python app.py for a desktop experience.

  • Configure start/end IPs, port lists, worker counts, timeouts, proxy pools, and Mullvad cycling.
  • Monitor a live results table with latency bars, MOTDs, version hints, and timestamps.
  • Inspect the Proxy Pool panel for health, lease counts, failure streaks, and cooldown timers.

Console / headless mode

Invoke python app.py --nogui when Tkinter is unavailable or undesirable.

  • Reuses the same scan loop, persistence layer, and proxy logic as the GUI.
  • Designed for remote servers, containers, and automation pipelines.
  • Extendable: define run_console_scan(app) or similar hooks in app.py to customise orchestration.

Persistence & exports

StorageManager writes artefacts continuously so you can pause and resume confidently.

  • Defaults to the user’s Desktop (auto-detected cross-platform).
  • Exports confirmed servers, open port leads, and GUI session state in human-friendly formats.
  • Point storage at shared directories to sync findings with teammates or CI runners.
Key artefacts

Know exactly what is produced after every sweep.

These files land automatically unless you override the destination path from the GUI or code.

Minecraft_Servers.txt

Confirmed servers with timestamps, MOTDs, version hints, latency, and player counts.

Open_Ports.txt

Leads that passed TCP checks but failed Minecraft protocol validation for further analysis.

saved_servers.json

Structured GUI state so tables repopulate on restart and long scans resume smoothly.

Proxy configuration

Maintain SOCKS5 endpoints in mcsmartscan/mullvadproxyips.txt; empty the file to disable proxying.

Automation & packaging

Ship the toolkit anywhere your team needs it.

Scripting helpers and CI workflows are already part of the repository.

PyInstaller bundle

Run pyinstaller.ps1 to invoke the curated build command and generate a Windows executable.

  • Wraps pyinstaller with the maintained minecraft_server_finder.spec recipe.
  • Bundles proxy lists and the mcsmartscan package for redistribution.
  • Matches the configuration used in the Build Windows Release GitHub Action.

Workstation bootstrap

install_system.bat installs Python prerequisites system-wide for GUI operators.

  • Upgrades pip and installs dependencies from requirements.txt.
  • Optional extras (mcstatus, python-nmap, psutil) can be added after the base install.
  • Ideal for labs where you need a consistent environment across multiple desktops.

Continuous integration ready

GitHub Actions workflows (.github/workflows) lint, test, and build the project on every push.

  • Runs the Python application workflow against Windows, macOS, and Linux runners.
  • Publishes Windows releases automatically when tagged (or triggered manually).
  • Keep local changes healthy by mirroring the CI steps: pytest, flake8, and the optional packaging flow.

All feature claims are sourced from app.py, the mcsmartscan package, and README.md. Verify changes in code before modifying these docs.