Go MC Scanner

An ultra-fast Minecraft server scanner and Masscan stream processor written in Go. Scans millions of IPs, resolves server software, parses MOTDs with ANSI colors, and extracts player samples in real time.

Why use this

Standard port scanners like Masscan or ZMap can find open TCP ports at wire speed, but they do not speak the Minecraft handshake protocol.

Go MC Scanner hooks directly into Masscan's stdout stream or reads IP lists to ping thousands of servers concurrently. It negotiates the protocol, grabs the MOTD, checks player counts, detects server software, and looks up the hosting ISP.

---

Features

• Masscan Pipe Support: Pipe live Masscan output directly into the scanner with zero disk bottlenecks (masscan ... | ./mc-scanner pipe).
• Software Detection: Detects Paper, Spigot, Purpur, Folia, Velocity, BungeeCord, NeoForge, LexForge, Leaves, and Vanilla.
• MOTD & Color Parser: Renders formatted Minecraft color codes and formatting in your terminal.
• Player Tracker: Records online players, max player limits, and sample player names.
• ISP & ASN Lookup: Automatically resolves server hosting providers (OVH, Hetzner, AWS, etc.).
• Discord Alerts: Optional webhook notifications for discovered servers.
• Standalone Binary: Zero dependencies. Compiled for Linux, Windows, and macOS.

---

Downloads

Grab the latest compiled binary from Releases:

• Linux: mc-scanner_linux_amd64.tar.gz (ideal for high-speed scanning on VPS / Dedicated servers)
• Windows: mc-scanner_windows_amd64.zip
• macOS: mc-scanner_darwin_amd64.tar.gz

Or build from source:

git clone https://github.com/zyrexdz/mc-scanner.git
cd mc-scanner
go build -o mc-scanner .
go build -o motd ./cmd/motd

---

Usage & Examples

1. Live Masscan Stream (Fastest)

Stream internet-wide open port results straight into the scanner:

masscan 0.0.0.0/0 -p 25565 --rate 1000000 --retries 2 -oL - 2>/dev/null | ./mc-scanner pipe hits.txt 4000 0 all all

2. Scan from Masscan Output File

./mc-scanner masscan masscan_results.txt hits.txt 4000 0 all all

3. Direct CIDR Range Scan

Scan specific subnets with custom port ranges:

./mc-scanner cidr subnets.txt hits.txt 2000 25565-25575 0 all all

4. Single Server MOTD Inspector

Inspect a single server's protocol and MOTD:

./motd play.hypixel.net:25565

---

Command Parameters

Usage (Pipe):
  mc-scanner pipe <output_file> <threads> <min_players> <version_range> <software_types> [keyword_file]

Usage (Masscan File):
  mc-scanner masscan <input_file> <output_file> <threads> <min_players> <version_range> <software_types> [keyword_file]

Usage (CIDR):
  mc-scanner cidr <cidr_file> <output_file> <threads> <port_range> <min_players> <version_range> <software_types> [keyword_file]

• threads: Number of concurrent worker routines (e.g. 2000 to 5000)
• min_players: Minimum online players required to save to hits file (0 for all servers)
• version_range: Filter by version (e.g. 1.20.4 or all)
• software_types: Filter by server type (e.g. paper, velocity, spigot, or all)

---

Optional Discord Webhook

Set the DISCORD_WEBHOOK_URL environment variable to receive embed alerts when servers are found:

export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
./mc-scanner pipe hits.txt 4000 0 all all

---

License

MIT