MCState.net API

Free REST API for Minecraft server and player data. Ping Java (TCP) and Bedrock (RakNet UDP) servers, look up player profiles and skin URLs by username or UUID, embed live status badges, and generate OpenGraph preview images. No authentication required. Rate limit: 20 req / min per IP.

OVERVIEW

GET/api/serverQuery server status (JSON)

GET/api/badge/{host}Live status badge (SVG)

GET/api/badge/{host}/{port}Live status badge — custom port (SVG)

GET/api/ogOG preview image (PNG)

GET/api/player/{username}Player profile & skin URL (JSON)

GET/api/mojang-statusMojang service status (JSON)

/api/server

ENDPOINT

GET

https://www.mcstate.net/api/server?host={host}&port={port}&edition={edition}

PARAMETERS

PARAMETERTYPEDESCRIPTION

host*

stringHostname or IP address of the Minecraft server

port

numberServer port (1–65535). Defaults to 25565 for Java, 19132 for Bedrock

edition

stringEdition to ping — "java" (TCP) or "bedrock" (RakNet UDP)(default: java)

* required

EXAMPLE REQUESTS

Java — default port (25565)

GET /api/server?host=mc.hypixel.net

Java — custom port

GET /api/server?host=play.example.com&port=25566

Bedrock — default port (19132)

GET /api/server?host=play.nethergames.org&edition=bedrock

Bedrock — custom port

GET /api/server?host=play.example.com&port=19133&edition=bedrock

Using fetch (JavaScript)

// Java
const res  = await fetch("https://www.mcstate.net/api/server?host=mc.hypixel.net");
const data = await res.json();
console.log(data.online, data.players.online);

// Bedrock
const res  = await fetch("https://www.mcstate.net/api/server?host=play.nethergames.org&edition=bedrock");
const data = await res.json();
console.log(data.online, data.gamemode);

RESPONSE FIELDS

FIELDTYPEDESCRIPTION

online

booleanWhether the server responded successfully

host

stringHostname as sent in the request

port

numberPort used for the connection

edition

string"java" or "bedrock"

latency

number | nullRound-trip ping time in milliseconds

version

string | nullServer version string (e.g. Paper 1.21.4)

protocol

number | nullMinecraft protocol version number (e.g. 769)

motd

stringMessage of the Day — may contain § formatting codes

subMotdBEDROCK

string | nullSecondary MOTD line (Bedrock only)

favicon

string | nullServer icon as base64 data URI (PNG 64×64). Java only.

players

object | nullPlayer counts and sample — see Players object below

gamemodeBEDROCK

string | nullGamemode reported by Bedrock server (e.g. "Survival")

error

string | nullHuman-readable error message when online is false

PLAYERS OBJECT

FIELDTYPEDESCRIPTION

players.online

numberCurrent number of online players

players.max

numberMaximum player slots

players.sample

arrayUp to 12 recently seen players, each with id (UUID) and name. Java only; always [] for Bedrock.

BEDROCKfield is only present in Bedrock Edition responses.

EXAMPLE RESPONSES

200 OKJava server online

{
  "online": true,
  "host": "mc.hypixel.net",
  "port": 25565,
  "edition": "java",
  "latency": 42,
  "version": "Hypixel BungeeCord",
  "protocol": 769,
  "motd": "Hypixel Network  [1.8-1.21]",
  "favicon": "data:image/png;base64,iVBORw0KGgoAAAA...",
  "players": {
    "online": 31847,
    "max": 200000,
    "sample": [
      { "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Notch" }
    ]
  }
}

200 OKBedrock server online

{
  "online": true,
  "host": "play.nethergames.org",
  "port": 19132,
  "edition": "bedrock",
  "latency": 38,
  "version": "1.21.50",
  "protocol": 800,
  "motd": "NetherGames Network",
  "subMotd": "Play.NetherGames.org",
  "favicon": null,
  "players": { "online": 4821, "max": 30000, "sample": [] },
  "gamemode": "Survival"
}

200 OKServer offline

{
  "online": false,
  "host": "offline.example.com",
  "port": 25565,
  "edition": "java",
  "error": "Server refused the connection — it may be offline or the port is closed."
}

400 Bad RequestMissing host parameter

{ "error": "Parameter 'host' is required." }

429 Too Many RequestsRate limit exceeded

{ "error": "Rate limit exceeded. Try again later." }

/api/badge

Embed a live status badge into your website or README. Returns an SVG image, cached for 30 seconds.

ENDPOINT

GET /api/badge/{host}
GET /api/badge/{host}/{port}

PATH PARAMETERS

PARAMETERTYPEDESCRIPTION

host*

stringHostname or IP address of the Minecraft server

port

numberServer port — use 19132 for Bedrock(default: 25565)

* required

EXAMPLES

Java (default port)

https://www.mcstate.net/api/badge/mc.hypixel.net

Custom port

https://www.mcstate.net/api/badge/mc.hypixel.net/25566

Bedrock

https://www.mcstate.net/api/badge/play.nethergames.org/19132

EMBED CODE

<!-- Markdown -->
![Server Status](https://www.mcstate.net/api/badge/mc.hypixel.net)

<!-- HTML -->
<img src="https://www.mcstate.net/api/badge/mc.hypixel.net" alt="Server Status"/>

Left side shows the hostname; right side shows status — online · 35k/200k or offline.

/api/og

Generates a 1200 × 630 PNG OpenGraph preview image for a given server. Used automatically for link previews when sharing a server URL. Shows status, player count, version, latency, MOTD and server favicon.

ENDPOINT

GET

https://www.mcstate.net/api/og?host={host}&port={port}

PARAMETERS

PARAMETERTYPEDESCRIPTION

host*

stringHostname or IP address of the Minecraft server

port

numberServer port — use 19132 for Bedrock. Edition is detected automatically.(default: 25565)

* required

EXAMPLE

Java server

GET /api/og?host=mc.hypixel.net

Bedrock server

GET /api/og?host=play.nethergames.org&port=19132

Embed as Open Graph meta tag

<meta property="og:image"
      content="https://www.mcstate.net/api/og?host=mc.hypixel.net" />

Response is a PNG image — not JSON. The image is generated server-side on every request (no cache). The left accent stripe is green when the server is online, red when offline. The edition badge is blue for Java, yellow for Bedrock.

/api/player/{username}

Look up a Minecraft Java Edition player by username. Returns the canonical name, UUID, skin texture URL and cape URL (if any). Data is sourced from the official Mojang API and cached for 5 minutes.

ENDPOINT

GET

https://www.mcstate.net/api/player/{username}

PATH PARAMETERS

PARAMETERTYPEDESCRIPTION

username*

stringMinecraft Java Edition username (3–16 chars) OR a UUID — with or without dashes

* required

EXAMPLE REQUESTS

Lookup by username

GET /api/player/Notch

Lookup by UUID (with dashes)

GET /api/player/069a79f4-44e9-4726-a5be-fca90e38aaf5

Lookup by UUID (no dashes)

GET /api/player/069a79f444e94726a5befca90e38aaf5

Using fetch (JavaScript)

// by username
const res  = await fetch("https://www.mcstate.net/api/player/Notch");
const data = await res.json();
console.log(data.uuid, data.skinUrl);

// by UUID
const res2 = await fetch("https://www.mcstate.net/api/player/069a79f444e94726a5befca90e38aaf5");
const data2 = await res2.json();
console.log(data2.name);

RESPONSE FIELDS

FIELDTYPEDESCRIPTION

name

stringCanonical username with correct capitalisation

uuid

stringUUID formatted with dashes (e.g. 069a79f4-44e9-...)

rawUuid

stringUUID without dashes — matches Mojang's internal format

skinUrl

string | nullDirect URL to the player's skin texture (64×64 PNG). Null if no custom skin.

capeUrl

string | nullDirect URL to the player's cape texture. Null if the player has no cape.

EXAMPLE RESPONSES

200 OKPlayer found

{
  "name": "Notch",
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "rawUuid": "069a79f444e94726a5befca90e38aaf5",
  "skinUrl": "http://textures.minecraft.net/texture/292009a4925b58f02c77dadc3ecef07ea4c7472f9b5b90da98a88a94535b0f9",
  "capeUrl": null
}

404 Not FoundPlayer not found

{ "error": "Player 'unknown_player' not found." }

400 Bad RequestInvalid username

{ "error": "Invalid username. Must be 3–16 characters (letters, numbers, underscore)." }

/api/mojang-status

Returns the real-time status of Mojang and Minecraft backend services — session server, API, textures, accounts and Microsoft auth. Useful for detecting outages that affect login, skins or multiplayer.

ENDPOINT

GET

https://www.mcstate.net/api/mojang-status

No parameters required. Results are not cached — each request performs a live check.

RESPONSE FIELDS

FIELDTYPEDESCRIPTION

services

arrayList of checked services — see Service object below

checkedAt

stringISO 8601 timestamp of when the check was performed

services[].id

stringInternal identifier (e.g. "session", "api", "textures")

services[].label

stringHuman-readable service name (e.g. "Session Server")

services[].desc

stringShort description of what the service does

services[].status

string"up" if the service responded, "down" if it timed out or errored

EXAMPLE RESPONSE

200 OKAll services operational

{
  "services": [
    { "id": "session",   "label": "Session Server", "desc": "Multiplayer authentication", "status": "up" },
    { "id": "api",       "label": "Mojang API",      "desc": "Player & name lookup",       "status": "up" },
    { "id": "textures",  "label": "Textures",        "desc": "Skins & capes",              "status": "up" },
    { "id": "website",   "label": "Minecraft.net",   "desc": "Main website",               "status": "up" },
    { "id": "accounts",  "label": "Accounts",        "desc": "Account management",         "status": "up" },
    { "id": "microsoft", "label": "Microsoft Auth",  "desc": "Microsoft login (new auth)", "status": "up" }
  ],
  "checkedAt": "2025-01-15T12:34:56.789Z"
}

429 Too Many RequestsRate limit exceeded

{ "error": "Rate limit exceeded. Try again later." }

NOTES

—Rate limit: 20 requests per minute per IP. Exceeding this returns HTTP 429 with a Retry-After header.
—Java timeout is 8 s (TCP). Bedrock timeout is 6 s (UDP). If the server does not respond, online will be false.
—Java edition automatically resolves SRV records (_minecraft._tcp) — use the same hostname as in the Minecraft client.
—MOTD may contain Minecraft § formatting codes (§a, §l, §#RRGGBB, etc.). Strip or render them client-side as needed.
—The favicon field contains a full data URI ready to use as an <img> src. Always null for Bedrock.
—players.sample is provided by the server and may be empty, partial, or contain fake entries. Always [] for Bedrock.
—Responses are cached server-side for 30 seconds. The X-Cache response header indicates HIT or MISS.

SUPPORT THE PROJECT

MCState.NET is free and open to everyone. If it saves you time, consider buying me a coffee ☕ or check out our server monitor.