MineScan API System

Minecraft server discovery & analytics

Home Analytics Documentation Server Browser Status

Available Endpoints

Query our database of Minecraft servers. All responses are JSON except where noted.

GET /server/{ip}

Look up if a specific server is in our database

Path Parameters
ip
string - required
Server IP like "127.0.0.1"
Example Request
GET https://mcapi.shit.vc/server/127.0.0.1
Sample Response
{
  "serverip": "127.0.0.1",
  "version": "1.20.1",
  "software": "Paper",
  "rawVersion": "Paper 1.20.1",
  "authmode": "online",
  "motd": "Welcome!",
  "onlinePlayers": 42,
  "maxPlayers": 100,
  "hasPlayers": true,
  "lastSeen": "2026-01-22T10:30:00",
  "isVanilla": false,
  "isEmpty": false,
  "isFull": false,
  "playerFillPercent": 42.0,
  "geolocation": {
    "country": "US",
    "countryName": "United States",
    "city": "New York",
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}
Server not found? You'll get a 404 response. Geolocation is included when available.
GET /servers

Browse and filter servers with pagination support

60 requests per minute
Query Options
version
string - optional
Match specific MC version like "1.20" or "1.19.4"
software
string - optional
Server type: paper, fabric, vanilla, etc
authmode
string - optional
Choose from: online, offline, whitelist
country
string - optional
Filter by country code (US, DE, GB) or full name (United States)
minPlayers
integer - optional - defaults to 0
Only show servers with this many players or more
sort
string - optional - defaults to lastseen
Order by: lastseen, players, version
page
integer - optional - defaults to 1
Which page (between 1 and 10000)
pageSize
integer - optional - defaults to 20
How many per page (1 to 100)
Example Requests
GET https://mcapi.shit.vc/servers?version=1.20&minPlayers=10
GET https://mcapi.shit.vc/servers?country=US&sort=players
GET https://mcapi.shit.vc/servers?software=paper&authmode=online&page=2
Sample Response
{
  "page": 1,
  "pageSize": 20,
  "count": 20,
  "total": 1523,
  "totalPages": 77,
  "sort": "lastseen",
  "servers": [
    {
      "serverip": "127.0.0.1",
      "version": "1.20.1",
      "software": "Paper",
      "onlinePlayers": 42,
      "maxPlayers": 100,
      "geolocation": {
        "country": "US",
        "countryName": "United States",
        "city": "New York",
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      ...
    }
  ]
}
Max 50k results total (page x pageSize can't exceed 50000)
GET /servers/random

Get randomly selected servers from our database

30 requests per minute
Query Options
count
integer - optional - defaults to 5
How many random servers (1 to 20)
version
string - optional
Filter by Minecraft version (e.g. 1.20.1)
minPlayers
integer - optional - defaults to 0
Filter by minimum player count
software
string - optional
Filter by server software type
country
string - optional
Filter by country code or name
Example Requests
GET https://mcapi.shit.vc/servers/random?count=10&minPlayers=5
GET https://mcapi.shit.vc/servers/random?country=DE&software=paper
Sample Response
{
  "count": 5,
  "servers": [...]
}
GET /ips

Export server IPs as plain text (newline separated)

3 requests per minute
Query Options
version
string - optional
Filter by version
software
string - optional
Filter by software
authmode
string - optional
Filter by auth type
country
string - optional
Filter by country code or name
minPlayers
integer - optional - defaults to 0
Minimum player count
limit
integer - optional - defaults to 100000
Max IPs to return (1 to 500k)
Example Requests
GET https://mcapi.shit.vc/ips?country=US&limit=1000
GET https://mcapi.shit.vc/ips?authmode=offline&minPlayers=10
Sample Response (text/plain)
127.0.0.1
192.168.1.169
192.168.1.142
This endpoint returns text/plain, not JSON
GET /whereis/{player}

Find where a player has been seen

30 requests per minute
Path Parameters
player
string – required
Minecraft username or UUID (partial matches allowed)
Query Options
limit
integer – optional – default 100
Maximum servers to return (1–1000)
Example Request
GET https://mcapi.shit.vc/whereis/Notch
Sample Response
{
  "uuid": "abcd-1234",
  "name": "Notch",
  "firstSeen": "2024-08-01T12:11:00Z",
  "lastSeen": "2026-01-25T18:42:10Z",
  "totalServers": 2,
  "servers": [
    {
      "ip": "127.0.0.1",
      "port": 25565,
      "firstSeen": "2024-08-01T12:11:00Z",
      "lastSeen": "2026-01-25T18:42:10Z"
    }
  ]
}
Partial name matches may return multiple players.
GET /who/{server_ip}

See which players have been seen on a server

30 requests per minute
Path Parameters
server_ip
string – required
Server IP address
Query Options
port
integer – optional
Server port (defaults to 25565)
limit
integer – optional – default 100
Maximum players to return (1–1000)
Example Request
GET https://mcapi.shit.vc/who/37.157.91.140
Sample Response
{
  "server": {
    "ip": "127.0.0.1",
    "port": 25565
  },
  "count": 2,
  "players": [
    {
      "uuid": "abcd-1234",
      "name": "Notch",
      "firstSeen": "2024-08-01T12:11:00Z",
      "lastSeen": "2026-01-25T18:42:10Z"
    }
  ]
}
Only players observed by MineScan are returned.

Player Data Notes

Player sightings are collected passively from observed server activity. This is not a live player list and may not reflect current online status.

Authentication Modes

online
Requires official Mojang account authentication
offline
Accepts cracked/non-premium clients
whitelist
Whitelist is enabled on this server

Response Field Reference

isVanilla
True when server runs unmodded Minecraft
isEmpty
True when no players are online
isFull
True when player count hits max capacity
playerFillPercent
How full the server is (0-100%)
geolocation
Server location data (country, city, coordinates) - included when available

Geolocation Fields

When available, server responses include a geolocation object with the following fields:

country
Two-letter country code (US, DE, GB, etc.)
countryName
Full country name (United States, Germany, etc.)
city
City name where the server is located
latitude
Geographical latitude coordinate
longitude
Geographical longitude coordinate