mcsrvstat.us APImcsrvstat.us ↗
Query live Minecraft Java and Bedrock server status via the mcsrvstat.us API. Get player counts, MOTD, version, icons, and debug metadata for any server address.
curl -X GET 'https://api.parse.bot/scraper/1e9174ec-7e1b-40a9-ab60-f6253c94084a/get_java_server_status?address=hypixel.net' \ -H 'X-API-Key: $PARSE_API_KEY'
Retrieve real-time status of a Minecraft Java Edition server (1.7+). Returns comprehensive server data including online status, player count, MOTD, version, icon, and debug/DNS information.
| Param | Type | Description |
|---|---|---|
| addressrequired | string | Server hostname or IP address (e.g., 'hypixel.net', 'mc.mineplex.com'). |
{
"type": "object",
"fields": {
"ip": "string, resolved IP address of the server",
"icon": "string, base64-encoded PNG server icon (data URI)",
"motd": "object with raw, clean, and html arrays of MOTD lines",
"port": "integer, server port",
"debug": "object containing diagnostic metadata (ping, query, dns, cache info)",
"online": "boolean, whether the server is currently reachable",
"players": "object containing online (integer) and max (integer) player counts",
"version": "string, Minecraft version required",
"hostname": "string, resolved hostname",
"protocol": "object with version (integer) and name (string)"
},
"sample": {
"data": {
"ip": "172.65.197.160",
"motd": {
"raw": [
"Hypixel Network [1.8/26.1]"
],
"html": [
"<span>Hypixel Network [1.8/26.1]</span>"
],
"clean": [
"Hypixel Network [1.8/26.1]"
]
},
"port": 25565,
"online": true,
"players": {
"max": 200000,
"online": 19788
},
"version": "Requires MC 1.8 / 1.21",
"hostname": "mc.hypixel.net",
"protocol": {
"name": "1.8.9",
"version": 47
},
"eula_blocked": false
},
"status": "success"
}
}About the mcsrvstat.us API
The mcsrvstat.us API exposes 4 endpoints for querying real-time Minecraft server status across both Java Edition (1.7+) and Bedrock Edition. Use get_java_server_status to retrieve up to 10 distinct response fields per server — including resolved IP, base64 server icon, MOTD variants, protocol version, and per-player counts — or use is_server_online for a lightweight online/offline check with player totals.
Java and Bedrock Server Status
The get_java_server_status endpoint accepts a address parameter (hostname or IP, e.g. hypixel.net) and returns a detailed status object: online boolean, players.online and players.max counts, a motd object with raw, clean, and html line arrays, version string, protocol with numeric version and name, and an icon field containing a base64-encoded PNG data URI. A debug object surfaces diagnostic metadata including ping, query, and DNS resolution info useful for troubleshooting unreachable servers.
Bedrock Edition Differences
get_bedrock_server_status covers Bedrock-specific fields absent from the Java endpoint: gamemode (e.g. Survival) and serverid, a unique identifier for the Bedrock server instance. Player list data appears under players.list when the server exposes it. Pass is_bedrock: true to the lighter is_server_online and get_server_icon endpoints to target Bedrock servers with those simpler queries.
Icon and Quick-Check Endpoints
get_server_icon returns the server's favicon as a data:image/png;base64,... string, or null if the server has no icon set — Bedrock servers rarely expose one. is_server_online is the minimal status check: it returns only online and the players object, suitable for monitoring dashboards where full metadata is unnecessary and response size matters.
- Displaying live player counts and MOTD on a Minecraft server listing site using
get_java_server_status - Monitoring whether a private or public Minecraft server is reachable via the
is_server_onlineendpoint - Rendering server icons in a custom launcher or network hub using the
iconfield fromget_server_icon - Detecting server protocol version for client compatibility checks via the
protocol.versionfield - Building Bedrock server dashboards that surface
gamemodeandserveridfromget_bedrock_server_status - Alerting when a server goes offline by polling
onlinestatus across a fleet of server addresses - Comparing Java vs Bedrock server uptime across a Minecraft network using both edition endpoints
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does mcsrvstat.us have an official developer API?+
What does the `debug` object in `get_java_server_status` contain?+
debug field returns diagnostic metadata about the server resolution attempt, including whether ping, query, and DNS lookups succeeded, and cache-related information. It is useful for diagnosing why a server appears offline when its address resolves but the game port is unreachable.Does the API return individual player names or UUIDs?+
players.online and players.max counts; individual player names and UUIDs are not currently exposed. The Bedrock endpoint includes an optional players.list array when the server makes that data available, but Java player lists are not covered. You can fork this API on Parse and revise it to add a player-list endpoint if the underlying source exposes that data for a specific server.What happens when a server is offline or the address doesn't resolve?+
online will be false, and fields like players, motd, and version will not be populated in the response. The debug object in the Java endpoint can indicate whether the failure was at the DNS, ping, or query stage.