Minecraft Server Finder

Why teams adopt it

High-throughput Minecraft discovery without sacrificing signal.

Every subsystem in Minecraft Server Finder originates from real-world sweeps where reliability, context, and repeatability mattered.

Deterministic address coverage

mcsmartscan.utils.permuted_index_generator reshuffles IPv4 ranges so every host is visited exactly once without hotspots.

Proxy-aware throughput

ProxyPool tracks SOCKS5 health, enforces cooldowns, and pairs neatly with the optional MullvadManager for VPN rotation.

Protocol-aware results

Java status handshakes expose version hints, MOTDs, and latency. Optional mcstatus and python-nmap add deeper context.

Operator-centric UI

Launch the Tkinter GUI for visual controls or run python app.py --nogui for a console flow in terminals and automation.

Structured persistence

StorageManager writes confirmed servers, open port leads, and GUI state to desktop-friendly files for later review.

Automatable releases

Use pyinstaller.ps1 for a reproducible Windows build and lean on GitHub Actions workflows for CI-tested exports.

Pipeline preview

Coordinated workers, resilient proxies, reliable storage.

This is the same pipeline the GUI, console shim, and automated jobs all ride on.

Address planning

ip_range_generator and permuted_index_generator prepare balanced work queues across massive IPv4 spans.

Parallel probes

ThreadPoolExecutor workers open sockets, negotiate handshakes, and track failure ratios to self-throttle.

Proxy arbitration

ProxyPool scores SOCKS5 endpoints while MullvadManager can rotate VPN exits to keep exit IPs fresh.

Result persistence

StorageManager writes text and JSON artefacts so you can resume sessions or feed results into other tooling.

Need the full breakdown? Head to How It Works for diagrams and module-level references.

Get scanning

Spin up the toolkit in minutes.

Everything ships in the repository. Only Python 3.10+ is required for the default experience.

Clone the repository and enter the directory.
Create and activate a virtual environment (recommended).
Install the required dependencies from requirements.txt.
Launch the Tkinter GUI or force console mode with --nogui.

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
python app.py
# or: python app.py --nogui

Enhance enrichment with optional extras such as mcstatus, python-nmap, psutil, and Mullvad CLI bindings.

Deep dives

Pick a guide that matches your next task.

Each subpage expands on the highlights with hands-on steps, diagrams, and references to the exact modules in the codebase.

Feature tour

Dive into every scanning, proxy, storage, and UI capability with pointers into the mcsmartscan package.

See features How the engine runs

Follow the request pipeline, worker orchestration, and data flow diagrams to understand how scans stay consistent.

Inspect architecture Operator playbook

Step-by-step guidance for GUI operators, console automation, proxy pools, PyInstaller builds, and test workflows.

Open guides Ethics and FAQ

Stay compliant with legal expectations, rate limiting best practices, and frequently asked questions from the community.

Review policy

Core facts

Everything here is pulled straight from the repository.

The numbers below reflect defaults in mcsmartscan.constants and behaviours enforced by the runtime.

0 Default worker threads orchestrated by the scan loop.

0 Seconds before TCP handshakes time out (tweakable per run).

0 Desktop OS targets covered in the GitHub Actions matrix.

0 Output artefacts persisted by StorageManager (servers, open ports, saved state).

Responsible scanning

Respect the rules of engagement.

The tool is powerful, but it is only appropriate where you have clear permission to test.

Operate with consent

Only sweep infrastructure you own or where written authorisation is in hand. Unauthorised scanning can violate laws and provider policies.

Balance performance and load

Adjust worker counts, proxy pools, and timeouts when testing shared networks so you remain within acceptable use policies.

Handle findings carefully

Results can surface sensitive MOTDs or player lists. Coordinate disclosure and respect privacy expectations from server operators.

Review the complete guidelines and FAQ on Ethics & FAQ before running broad scans.

Map Minecraft servers with production-grade tooling.