Minecraft Server Scanner with Web UI

A high-performance Minecraft server scanner with a modern web interface. Built with Flask and optimized for speed, this tool can scan thousands of servers concurrently while providing real-time results and filtering.

Features

• Shodan Integration - Real-time searches with automatic parsing
• JSON Export Search - Import and search through Shodan JSON exports locally (Save API credits!)
• High-Performance Scanning - 100 concurrent pings, 1-second timeouts
• Smart File Handling - Auto-detects ip-port_*.txt, shodan_output_*.txt, and generic files
• Modern Web Interface - Real-time updates, progress tracking, advanced filtering
• Advanced Features - Export filtered results, ignore lists, scan cancellation
• Automatic Shodan Result Saving - Prevents wasted use of API credits, re-scan old results for server activity!
• Complex Boolean Queries - Support for AND, OR, NOT, and parentheses in JSON searches

Why Make This?

What better way to give company to those servers with only one player in it!

Requirements

• Python 3.7+

Installation

1. Clone & Install

git clone https://github.com/cev-api/minecraft-server-scanner.git
cd minecraft-server-scanner
pip install -r requirements.txt

2. Configure Settings

Edit settings.json:

{
    "shodan_api_key": "your_shodan_api_key_here",
    "concurrent_pings": 100,
    "ping_timeout": 1,
    "max_workers": 50,
    "server_host": "0.0.0.0",
    "server_port": 5000,
    "server_threads": 100
}

3. Set Up Ignore List (Optional)

Create ignore.txt:

192.168.1.1:25565
10.0.0.1:25565

Usage

Start Server

python app.py

Web interface available at http://localhost:5000

Web Interface

• Shodan Search - Enter regex queries like "City: Blahtown AND (1.27.1 OR 1.28.1) or Fabric AND 1.27.1 (automatically adds "minecraft" prefix)
• JSON Search: Import Shodan JSON exports and search locally
• IP:Port Scanner - Load and ping server lists from files
• Advanced Filtering - Show active players only, online servers only
• Export Results - Save filtered results to exported_*.txt files

Shodan JSON Exports (.json)

• JSONL format - one JSON object per line
• Rich metadata - IP, port, data, location, version, hostnames
• Local search - no API calls needed
• Complex queries - boolean expressions with AND, OR, NOT, parentheses

Troubleshooting

• Slow scanning: Check internet speed, verify concurrent_pings setting
• Scrolling lag: Interface uses hardware acceleration, large lists may have slight delays
• Server won't start: Check port 5000 availability, verify dependencies
• JSON search issues: Ensure JSON file is valid JSONL format
• Crashing Browser: Too many servers!