Minecraft Java Server Status & Player Count Monitor

Check supplied public Minecraft Java Edition servers for online/offline status, current player counts, player capacity, version, and MOTD. Each run queries mcsrvstat.us and emits timestamped snapshots for status pages, community bots, server inventories, and scheduled monitoring.

This Actor uses the Java status endpoint; it does not query the separate Bedrock endpoint. Provider results may be cached for up to five minutes, and the Actor emits snapshots—not persisted uptime history or native alerts.

Built for

• Public server dashboards and status pages
• Community bots and availability checks
• Player-count snapshots and scheduled reporting

How lookup works

This Actor does not open a Minecraft protocol connection itself. It queries the public api.mcsrvstat.us/3/<address> Java status endpoint for each supplied host, not the separate /bedrock/3/<address> endpoint. A paid record is emitted only when that provider returns a valid payload containing an explicit Boolean online value.

When a port is omitted, the provider query also omits it so Minecraft SRV discovery remains available. Output host and port identify the provider-resolved endpoint; requestedHost and optional requestedPort preserve what you supplied.

Provider timeouts, HTTP failures, malformed payloads, and oversized responses are skipped. They are not mislabeled or charged as an offline server.

Input

{
  "servers": ["mc.hypixel.net", "example.org:25570", "[2001:db8::1]:25565"],
  "maxItems": 25,
  "requestTimeoutSecs": 30
}

Ports must be between 1 and 65535. Bracketed hosts must be valid IPv6 literals. Schemes, paths, credentials, and query strings are rejected.

Output

{
  "host": "mc.example.org",
  "port": 25565,
  "requestedHost": "play.example.org",
  "online": true,
  "version": "1.21.1",
  "playersOnline": 42,
  "playersMax": 200,
  "motd": "Welcome",
  "lookupProvider": "api.mcsrvstat.us",
  "sourceUrl": "minecraft://mc.example.org:25565",
  "detectedAt": "2026-08-26T12:00:00.000Z",
  "dedupeKey": "minecraft|mc.example.org:25565"
}

The example illustrates the schema; current server state comes from the run.

Limits

• Checks only user-supplied hosts; it does not scan address ranges or discover servers.
• Provider results may be cached for up to five minutes.
• Provider responses are capped at 256 KB.
• This Actor emits snapshots, not persisted uptime history, SLA calculations, or native alerts. Schedule runs and upsert by dedupeKey if you need to retain snapshots across runs.
• Processing stops at maxItems or the Apify PPE charge limit.

Local verification

npm ci
npm run lint
npm test
npm run typecheck
npx --yes apify-cli validate-schema

Production uses Node.js 24, npm 12.0.2, a committed npm lockfile, and Oxc (oxlint).