mcsrvstat 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.
What is the mcsrvstat 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.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace mcsrvstat-us-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Minecraft Server Status API — check servers, read details, fetch icons."""
from parse_apis.minecraft_server_status_api import MinecraftServers, IsBedrock, ServerNotFound
client = MinecraftServers()
# Full Java server status — typed fields on the returned JavaServer resource.
java = client.javaservers.get(address="hypixel.net")
print(f"Java server: {java.hostname}, online={java.online}, players={java.players.online}/{java.players.max}")
print(f" Version: {java.version}, protocol: {java.protocol.name}")
print(f" MOTD: {java.motd.clean[0]}")
# Full Bedrock server status.
bedrock = client.bedrockservers.get(address="play.histeria.fr")
print(f"Bedrock server: {bedrock.hostname}, online={bedrock.online}, gamemode={bedrock.gamemode}")
print(f" Players: {bedrock.players.online}/{bedrock.players.max}, version={bedrock.version}")
# Quick online check — lightweight, returns only status + player counts.
status = client.serverstatuses.check(address="hypixel.net")
print(f"Quick check: online={status.online}, players={status.players.online}")
# Fetch server icon as base64 data URI.
icon_result = client.servericons.fetch(address="hypixel.net")
has_icon = icon_result.icon is not None
print(f"Icon present: {has_icon}")
# Typed error handling for an invalid server address.
try:
client.javaservers.get(address="nonexistent.invalid.server.xyz")
except ServerNotFound as exc:
print(f"Server not found: {exc.address}")
print("exercised: javaservers.get / bedrockservers.get / serverstatuses.check / servericons.fetch / ServerNotFound")
Retrieve real-time status of a Minecraft Java Edition server (1.7+). Returns comprehensive server data including online status, player count, MOTD, version, icon, protocol, and debug/DNS information. The response always includes the 'online' boolean; when offline, most other fields are absent.
| 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",
"icon": "data:image/png;base64,iVBOR...",
"motd": {
"raw": [
"§f §aHypixel Network §c[1.8/26.1]"
],
"html": [
"<span>Hypixel Network [1.8/26.1]</span>"
],
"clean": [
" Hypixel Network [1.8/26.1]"
]
},
"port": 25565,
"debug": {
"srv": true,
"ping": true,
"query": false,
"bedrock": false,
"ipinsrv": false,
"cachehit": false,
"apiversion": 3,
"cnameinsrv": false,
"animatedmotd": false,
"querymismatch": false
},
"online": true,
"players": {
"max": 200000,
"online": 20079
},
"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 API
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.
The mcsrvstat API is a managed, monitored endpoint for mcsrvstat.us — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when mcsrvstat.us changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official mcsrvstat.us API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.