Documentation

Complete guide to understanding and using MCScans. Learn how our platform works, explore the API, and discover advanced features for Minecraft server analysis.

Overview

MCScans is a comprehensive Minecraft server scanning platform that continuously monitors and analyzes thousands of Minecraft servers across the internet. Our system provides recent data about server status, player counts, versions, and much more.

🔍 Continous Scanning

Continuous monitoring of Minecraft servers with up-to-date information about player counts, server versions, and online status.

📊 Comprehensive Data

Detailed server information including MOTD, player lists, protocol versions, and historical data tracking.

🔧 Powerful API

RESTful API with advanced filtering, sorting, and pagination capabilities for seamless integration into your applications.

📈 Historical Archives

Automatic archiving of historical server data, allowing you to track server version shifts, player trends, and server uptime over time.

How It Works

1

Server Discovery

Our scanning infrastructure continuously discovers new Minecraft servers through various methods, namely zmap scans from various IPs.

2

Data Collection

Each discovered server is pinged using the Minecraft Server List Ping packet to gather information such as player count, server version, MOTD, and favicon.

3

Data Processing

Collected data is processed, validated, and stored in our database. We perform deduplication, data normalization, and quality checks to ensure accuracy.

4

API & Web Interface

The processed data is made available through our web interface and RESTful API, allowing users to search, filter, and analyze Minecraft server data.

Scanning Process

Our scanning process is designed to be efficient, respectful, and comprehensive. Here's how we ensure accurate and up-to-date server information:

Scanning Frequency

  • Passive Global: Scanned every 3-7 days
  • Passive Heartbeat: Scanned every 5 minutes
  • Active Scanning: Planned

Data Points Collected

Server Information

  • • Server IP and Port
  • • Protocol Version
  • • Server Version
  • • MOTD (Message of the Day)
  • • Server Favicon

Player Data

  • • Current Player Count
  • • Maximum Player Slots
  • • Online Player List

API Overview

The MCScans API provides programmatic access to our entire database of Minecraft server information. Built with REST principles, it offers intuitive endpoints for searching, filtering, and retrieving server data.

Base URL

https://api.mcscans.fi/public/v1/

🚀 Features

  • • RESTful API design
  • • JSON response format
  • • Advanced filtering & sorting
  • • Pagination support
  • • Real-time data
  • • Historical data access

📊 Response Format

  • • Consistent JSON structure
  • • Error handling with HTTP codes
  • • Metadata for pagination
  • • Timestamps in ISO 8601
  • • UTF-8 encoding

API Endpoints

GET /servers

Retrieve a list of all scanned Minecraft servers with optional filtering and sorting.

Query Parameters

page=1 // Page number (default: 1)
edition="Java" | "Bedrock" // Filter by game edition
software="Paper" // Filter by server software
version="1.20.1" // Filter by version
source="Global" | "China" // Filter by source
sort="player" | "proto" // Sort by: player count, protocol version
authMode="Online" | "Offline" | "Whitelist" // Filter by authentication mode
geo=true // Enable geographic location lookup
live=true // Filter by live status (active in the past 5 minutes)

Example Response

{
    "totalServers": 1000,
    "servers": [
        {
            "hostname": "172.24.67.89",
            "port": 25565,
            "motd": "Welcome to MCScans!",
            "favicon": {
                "icon": "data:image/png;base64,...",
                "hash": "a498775a"
            },
            "pluginCount": null,
            "playerStats": {
                "maxPlayers": 200000,
                "onlinePlayers": 47823
            },
            "ping": {
                "latency": 0,
                "protocol": 109,
            }
            "players": {
                "ping": [
                    {
                        "uuid": "08dae07c-2bb3-333f-955c-fdef1f438c97",
                        "username": "Thienanbell"
                    }
                ],
                "real": []
            }
            "modInfo": [
                {
                "name": "Create",
                "version": "1.0.0"
                }
            ],
            "authMode": 1, // 0 = Offline, 1 = Online, 2 = Whitelist
            "version": "1.20.4",
            "software": "Forge",
            "timestamp": "2025-06-17T12:40:50.732180",
            "serverType": "",
            "tags": ["historical", "China"],
            "geo": { ... } // Optional geographic data
        },
        { ... }
    ]
}

Authentication

Currently, the MCScans API is publicly accessible without authentication. However, we plan to implement API keys for enhanced features and higher rate limits in the future.

🔮 Future Authentication

We're working on implementing API key authentication to provide:

  • • Higher rate limits for authenticated users
  • • Increased results per page (20 -> 50)

Current Usage

For now, simply make requests to our API endpoints without any authentication headers:

curl -X GET "https://api.mcscans.fi/public/v1/servers" \
  -H "Accept: application/json"

Rate Limiting

To ensure fair usage and maintain service quality, we implement rate limiting on our API endpoints.

⚡ Current Limits

  • Requests per minute: 60
  • Requests per hour: 1,000
  • Concurrent connections: 5
  • Burst limit: 10 requests

📊 Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

🚫 Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 status code with the following response:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message: "Rate limit exceeded: CONTEXT.MAX requests per CONTEXT.AFTER",
  "retryAfter": CONTEXT.AFTER
}

Search & Filtering

MCScans provides powerful search and filtering capabilities to help you find exactly the servers you're looking for, whether through our web interface or API.

🔍 Search Types

  • Regex Search:
    Search in server ip, port, software, version, motd.

🎯 Filter Options

  • Software:
    BungeeCord, Paper, Spigot, Forge, etc.
  • Version:
    Minecraft version (e.g., 1.20.4)
  • Source:
    Either Global or China

Advanced Search Examples

Find Popular Survival Servers

GET /servers?query=survival&sort=player

Find 1.20 Servers with PvP

GET /servers?query=pvp&version=1.20

Data Sorting

Sort server results by various criteria to find the most relevant servers for your needs.

👥 Player Count

Sort by current online players

?sort=player

🎮 Protocol Version

Sort by Minecraft version

?sort=proto

📶 Timestamp

Sort by last seen timestamp

?sort=timestamp

Historical Records

MCScans automatically archives historical server data, providing valuable insights into server trends, player growth, and long-term statistics.

✨ New in v1.0.1

Servers that are no longer detected by our scanners are now automatically archived while remaining accessible through both the API and web interface.

📊 What We Track

The same data as an active server, simply stored for later use.

🔍 Archive Status

  • ● Active: Seen in last scan
  • ● Historical: Legacy data only

Access Historical Data

Records that are historical will have the "tags" property that includes the "historical" tag.

Dataset API Overview

The Dataset API provides access to our historical archives of Minecraft server data. It allows you to download comprehensive datasets for offline analysis, research, and integration into your projects.

Base URL

https://data.mcscans.fi/api/

Dataset API Endpoints

GET / (Base Endpoint)

Retrieve a list of all datasets available for download.

Example Response

{
  "files": [
    {
      "type": "directory",
      "name": "587f4d4e-b827-4aec-8737-a2096219d040",
      "children": [
        {
          "type": "file",
          "name": "Java_results.json",
          "size": 893322658,
          "mtime": "2026-03-01T19:42:42.961Z",
          "lines": 157726
        },
        {
          "type": "file",
          "name": "Java_zmap.csv",
          "size": 33877246,
          "mtime": "2026-03-01T12:17:40.033Z",
          "lines": 2369540
        }
      ],
      "mtime": "2026-03-01T19:42:42.961Z"
    },
    {
      "type": "directory",
      "name": "4abf1b3e-2adb-449f-b6d7-a9768db05d58",
      "children": [
        {
          "type": "file",
          "name": "Java_results.json",
          "size": 900135641,
          "mtime": "2026-02-28T15:36:46.549Z",
          "lines": 156704
        },
        {
          "type": "file",
          "name": "Java_zmap.csv",
          "size": 33522619,
          "mtime": "2026-02-28T12:00:20.611Z",
          "lines": 2343882
        }
      ],
      "mtime": "2026-02-28T15:36:46.549Z"
    },
    { ... }
  ]
}

Dataset Structure

📁 Directory Names

Each directory name (e.g., 587f4d4e-b827-4aec-8737-a2096219d040) represents a unique Scan ID. This UUID corresponds to a specific scan session conducted on a particular date.

📄 File Types
Java_results.json / Java_results.json.gz

Contains Minecraft JSONL data (JSON Lines format). Each line represents a scanned Minecraft server with complete information including hostname, port, MOTD, player stats, version, and more.

Java_zmap.csv / Java_zmap.csv.gz

Contains a line-by-line IP list of addresses that responded to TCP ping on port 25565. ⚠️ Important: These IPs are not guaranteed to be Minecraft servers - they are simply hosts that responded to TCP connection attempts.

💡 Tip

Files with .gz extension are compressed using gzip. You can decompress them using standard tools like gunzip or by using compression libraries in your preferred programming language.

Downloading Files

📥 How to Download

After obtaining the directory UUID and file name from the API, you can download the actual files from:

https://data.mcscans.fi/{uuid}/{filename}

Example:

https://data.mcscans.fi/587f4d4e-b827-4aec-8737-a2096219d040/Java_results.json
🔧 Download Example (cURL)
# Download uncompressed file
curl -O https://data.mcscans.fi/587f4d4e-b827-4aec-8737-a2096219d040/Java_results.json

# Download compressed file
curl -O https://data.mcscans.fi/587f4d4e-b827-4aec-8737-a2096219d040/Java_results.json.gz
gunzip Java_results.json.gz

Data Formats

Understanding the structure and format of data returned by MCScans API endpoints.

Server Object Structure

{
    "hostname": "172.24.67.89",
    "port": 25565,
    "motd": "Welcome to MCScans!",
    "favicon": {
        "icon": "data:image/png;base64,...",
        "hash": "a498775a"
    },
    "pluginCount": null,
    "playerStats": {
        "maxPlayers": 200000,
        "onlinePlayers": 47823
    },
    "ping": {
        "latency": 0,
        "protocol": 109
    },
    "players": {
        "ping": [
            {
                "uuid": "08dae07c-2bb3-333f-955c-fdef1f438c97",
                "username": "Thienanbell"
            }
        ],
        "real": []
    },
    "modInfo": [
        {
            "name": "Create",
            "version": "1.0.0"
        }
    ],
    "authMode": null,
    "version": "1.20.4",
    "software": "Forge",
    "timestamp": "2025-06-17T12:40:50.732180",
    "serverType": "",
    "tags": ["historical", "China"]
}

📅 Timestamp Format

All timestamps use ISO 8601 format:

"2025-06-18T14:45:00Z"

UTC timezone, with millisecond precision when available

🌈 MOTD Formatting

Two format options:

  • motd: Original with § codes
  • motd_normalized: Original with § codes but converts special fancy characters to normal characters, useful for text processing

Integration Guide

Learn how to integrate MCScans API into your applications with these practical examples and best practices.

🟨 JavaScript Example

async function getPopularServers() {
  try {
    const response = await fetch(
      'https://api.mcscans.fi/public/v1/servers?' +
      'sort=player&software=Paper&query=SMP'
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    return data.data;
  } catch (error) {
    console.error('Error fetching servers:', error);
    return [];
  }
}

💡 Best Practices

  • • Respect rate limits: Implement exponential backoff for failed requests
  • • Cache responses: Store frequently accessed data locally
  • • Handle errors gracefully: Always check HTTP status codes
  • • Monitor usage: Check rate limit headers in responses
  • • Validate data: Servers may go offline between requests
  • • Use our public dataset: Instead of scraping our entire API, just download the public dataset on the Datasets page for more efficient data access

🔧 Common Use Cases

Attack Prevention

Detect which servers are accidentally exposed

Monitoring Tools

Track server uptime and player trends

Analytics Dashboards

Visualize Minecraft community statistics

Discord Bots

Integrate our API to provide info in Discord

Data Removal

Prevent Future Scanning: Blacklist Your Server

If you want to prevent MCScans from scanning your server in the future, you can visit our blacklist page to add your server to our exclusion list. This will stop future scans.

Problem: I want to remove my server data from MCScans

MCScans only scans publicly accessible Minecraft servers — similar to how search engines index public websites. If your server is publicly reachable, we consider it fair game for passive data collection. That said, we understand some server owners may have valid concerns. While we don’t offer blanket removal, we’re open to reviewing exceptional cases. If you believe you have a compelling reason for removal, feel free to contact us via a ticket on discord.

Query Modes

Two query modes are available for querying the MCScans database.

This feature is not available via the public API route, only via the web interface.

🔍 Regex Search

Simple regex search across multiple fields:

Searches: hostname, ip, port, software, version, serverType, motd, motd_normalized

Match: Case-insensitive partial matching (exact match for port) + regex

survival

Select all servers where any field contains "survival"

⚡ Modern Search

Advanced syntax with operators and field targeting:

record.hostname="103.1.215.33"

Select all servers where hostname equals "103.1.215.33"

record.motd="Invalid hostname%"

Select all servers where MOTD starts with "Invalid hostname"

record.version!="TCPShield.com"

Select all servers where version is not "TCPShield.com"

record.hostname="103.1.215.33" AND record.port=25565

Select all servers where hostname is "103.1.215.33" and port is 25565

record.tags CONTAINS ["China"]

Select all servers where tags array contains "China"

record.tags NOT CONTAINS ["China", "historical"]

Select all servers where tags array does not contain "China" or "historical"

record.ping.protocol>=700

Select all servers where ping protocol version is 700 or higher

NOT record.motd="A minecraft%"

Select all servers where MOTD does not start with "A minecraft"

⚠️ Query Type Auto-Inference

The query type is automatically inferred based on the syntax used and does not need to be selected explicitly.