Minecraft Server Status Scraper

Check Minecraft server status for batches of known public hostnames and export one timestamped row per endpoint. The Actor uses the public mcsrvstat.us API to report online state, resolved host and port, players, version, protocol, MOTD, software, favicon, cache/debug context, and lookup time.

Use it for server directories, community dashboards, scheduled uptime snapshots, migrations, or spreadsheet exports. It checks only hostnames you provide. It does not scan IP ranges or discover private servers.

What does Minecraft Server Status Scraper do?

For each unique supplied endpoint, the Actor:

1. validates the public DNS hostname and optional port;
2. chooses the Java or Bedrock mcsrvstat.us v3 endpoint;
3. performs a bounded HTTP lookup with timeout and transient retries;
4. normalizes optional fields into one stable dataset shape;
5. preserves source-confirmed offline responses as explicit rows;
6. preserves exhausted upstream failures as explicit, uncharged error rows.

The default dataset is ready for JSON, CSV, Excel, API, webhook, and integration use.

Who is it for?

• Server directory operators refreshing availability and player counts.
• Community managers checking whether known servers are reachable.
• Developers enriching a server list with version, protocol, and MOTD fields.
• Data teams exporting timestamped snapshots to a warehouse or spreadsheet.
• Operations teams scheduling recurring checks and comparing changes downstream.

Why use this Actor?

• Batch input instead of one manual status page at a time.
• Java and Bedrock endpoint selection per server.
• Stable typed output even when optional game-server fields are absent.
• Explicit online, offline, and error outcomes.
• DNS SRV/CNAME resolution context exposed by mcsrvstat.us.
• Source cache timestamps for interpreting repeated checks.
• No browser, account, cookie, proxy, or API key required.
• Conservative concurrency and bounded retries.

What Minecraft server data can I extract?

Group	Fields
Request	input, inputIndex, requestedHost, requestedPort, edition
Status	status, online, errorType, errorMessage
Resolved endpoint	resolvedHostname, resolvedIp, resolvedPort
Players	playersOnline, playersMax, playerNames
Compatibility	version, protocolVersion, protocolName, software, plugins, mods, eulaBlocked
World and game mode	mapRaw, mapClean, mapHtml, gameMode, serverId
Presentation	motdRaw, motdClean, motdHtml, infoRaw, infoClean, infoHtml, icon
Cache	cacheHit, cacheTime, cacheExpiresAt
Diagnostics	debugPing, debugQuery, debugSrv, debugBedrock, debugErrors
Provenance	sourceUrl, lookupMs, checkedAt

Optional values are null or empty arrays when a server does not expose them. Many servers intentionally hide player samples or software names. plugins and mods are arrays of { "name": "ExamplePlugin", "version": "1.0" } entries (version may be null). serverId is a string to preserve large Bedrock IDs exactly; gameMode and serverId are normally Bedrock-only, and eulaBlocked is Java-only. World/map and server-information fields depend on what the server exposes. HTML fields are untrusted data: escape or sanitize them before displaying on a website.

How to check Minecraft server status

1. Open the Actor in Apify Console.
2. Add one or more known public hostnames under Minecraft servers.
3. Use an object when you need a custom port or Bedrock mode.
4. Choose a maximum row count and conservative concurrency.
5. Click Start.
6. Open the dataset and export the overview or complete fields.
7. Add an Apify schedule if you need recurring snapshots.

A useful first input is:

{
  "servers": [
    { "host": "play.cubecraft.net", "edition": "java" },
    { "host": "mc.mineplex.com", "edition": "java" },
    { "host": "invalid.invalid", "edition": "java" }
  ],
  "maxItems": 3,
  "concurrency": 3
}

Input parameters

servers

Required array with 1–1,000 entries before duplicate removal. Console's structured input uses objects: each has host, optional port, and edition set to java or bedrock. Direct runtime/API callers can also supply legacy strings such as "play.cubecraft.net" or "play.cubecraft.net:25565"; strings use Java edition. Use objects for mixed Java/Bedrock batches.

Only DNS hostnames are accepted. URLs, IP address ranges, raw IP addresses, local names, paths, and query strings are rejected. Duplicate edition/host/port combinations are checked once.

maxItems

Maximum unique endpoints checked, from 1 to 1,000. Schema-defaulted execution on Apify (including Console and API runs) uses 20 when maxItems is omitted. Set it explicitly to check more endpoints. Only truly raw runtime input that bypasses schema defaults falls back to all supplied unique endpoints (up to 1,000). All entries are validated before charging; valid endpoints beyond the effective limit are not requested.

concurrency

Concurrent source requests, from 1 to 10. The default is 5. Lower values are useful for gentle scheduled workloads.

requestTimeoutSecs

Timeout for each attempt, from 5 to 60 seconds. The default is 20 seconds.

maxRequestRetries

Additional attempts for network failures, timeouts, HTTP 429, and temporary 5xx responses. Allowed values are 0–3; the default is 2. Backoff is bounded. Malformed inputs and valid offline responses are not retried.

Output example

A current online Java response has this normalized shape (the IP is anonymized here):

{
  "input": "play.cubecraft.net",
  "inputIndex": 0,
  "requestedHost": "play.cubecraft.net",
  "requestedPort": null,
  "edition": "java",
  "status": "online",
  "online": true,
  "resolvedHostname": "play.cubecraft.net",
  "resolvedIp": "203.0.113.42",
  "resolvedPort": 25565,
  "playersOnline": 288,
  "playersMax": 5000,
  "playerNames": [],
  "version": "We support: 1.20-1.21",
  "protocolVersion": 340,
  "protocolName": "1.12.2",
  "motdClean": ["CubeCraft Games [EU]", "NEW GAME: MOB HUNT"],
  "software": null,
  "cacheHit": true,
  "debugPing": true,
  "debugQuery": false,
  "sourceUrl": "https://api.mcsrvstat.us/3/play.cubecraft.net",
  "lookupMs": 184,
  "checkedAt": "2026-09-09T04:10:01.000Z"
}

The full dataset also includes raw/HTML MOTD, icon, cache times, debug fields, and error details.

Online, offline, and error rows

status: "online" means mcsrvstat.us reached the game server.

status: "offline" means the source completed the check but could not establish an online server. The row may still include DNS resolution and probe errors. This is a useful monitoring result and is charged as a server status.

status: "error" means the mcsrvstat.us HTTP request itself failed after bounded retries or returned an invalid response. Error rows are exported for auditability and are not charged per status.

A single offline endpoint does not fail the batch. An all-error batch remains explicit error rows, never false offline statuses. Invalid input fails closed before charging or status requests begin.

Completed rows are saved incrementally in the original deduplicated input order, with a bounded look-ahead window. A slow earlier endpoint can delay later rows, but no entire-batch buffer is required. When the SDK reports that no more statuses can be charged, the Actor stops scheduling new lookups; already in-flight requests may finish. Uncharged online/offline rows are not stored.

Schedule recurring uptime snapshots

Apify schedules can run the same input hourly, daily, or on another cadence. Each run creates a separate default dataset with checkedAt timestamps and source cache information.

For a monitoring workflow:

1. save the known hostname list as a Task;
2. attach a schedule;
3. send completed datasets to your database or webhook;
4. compare each endpoint's latest status, playersOnline, version, and motdClean against the previous snapshot;
5. trigger alerts in your own workflow when values change.

The Actor exports snapshots; it does not keep history, compare prior runs, or send alerts by itself.

Export to spreadsheets and data pipelines

From the Dataset tab, choose JSON, CSV, Excel, XML, or RSS. For automated pipelines, fetch dataset items using defaultDatasetId from the run response.

Useful downstream keys are:

• input for a stable requested endpoint;
• checkedAt for snapshot ordering;
• status for availability;
• playersOnline for activity;
• version for compatibility changes;
• motdClean for display text;
• cacheHit and cacheTime for freshness interpretation.

How much does it cost to check Minecraft servers?

Pricing uses one small run-start event plus one server-status event for every valid online or offline row. Upstream request errors have no per-status charge.

Current BRONZE pricing examples:

Useful status rows	Estimated BRONZE event total
1	0.00228 USD
10	0.02190 USD
100	0.21810 USD

Each total is the $0.0001 start fee plus $0.00218 per status on BRONZE. Apify plan tiers can have different per-status rates: FREE $0.002507, SILVER $0.0017004, and GOLD/PLATINUM/DIAMOND $0.001308. Your final run total can also be constrained by the maximum run charge you configure.

API usage with cURL

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~minecraft-server-status-lookup/runs?token=$APIFY_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"servers":[{"host":"play.cubecraft.net"},{"host":"mc.mineplex.com"}],"maxItems":2}'

Fetch the resulting dataset using the defaultDatasetId returned by the run API.

API usage with JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/minecraft-server-status-lookup').call({
  servers: [{ host: 'play.cubecraft.net' }, { host: 'mc.mineplex.com' }],
  maxItems: 2,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

API usage with Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/minecraft-server-status-lookup').call(run_input={
    'servers': [{'host': 'play.cubecraft.net'}, {'host': 'mc.mineplex.com'}],
    'maxItems': 2,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

Use with MCP and AI agents

Add the Actor to Claude Code:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/minecraft-server-status-lookup"

Claude Desktop, Cursor, and VS Code use this MCP JSON configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/minecraft-server-status-lookup"
    }
  }
}

Example prompts:

• “Check play.cubecraft.net and mc.mineplex.com as Java servers and summarize online players.”
• “Run my saved Minecraft status Task and return endpoints whose status is offline.”
• “Export version and MOTD fields for these known Java server hostnames.”

Tips for reliable results

• Prefer the hostname players actually use; DNS SRV records may select a non-default port.
• Set edition: "bedrock" explicitly for Bedrock servers.
• Do not schedule faster than the source cache expiry if you need meaningfully new data.
• Treat optional fields as nullable in downstream transformations.
• Use status, not only online, because error rows intentionally have online: null.
• Keep concurrency conservative for long recurring lists.
• Compare cacheTime as well as checkedAt when judging freshness.

Limitations

• Data is provided by mcsrvstat.us and the target Minecraft server at check time.
• A server can block status pings, hide player samples, or omit software metadata.
• lookupMs measures the API request and retries, not direct game-server network latency from the Actor container.
• mcsrvstat.us documents five-minute source caching, so repeated runs may receive the same underlying check. Inspect the source cache timestamps for each response.
• A clean MOTD is source-normalized; raw formatting is retained separately.
• The Actor does not scan CIDR ranges, ports, or the public internet.
• The Actor does not discover servers, retain historical state, compare runs, or deliver alerts.
• A hostname resolving privately or unexpectedly is handled by the upstream public service; submit only endpoints you are authorized to monitor.

Legality and responsible use

Check only public server hostnames you are authorized to query. Respect community rules, privacy expectations, Apify's terms, and mcsrvstat.us usage expectations. Player samples may contain public in-game names; minimize retention and avoid using them for profiling or harassment.

This tool is designed for known-host metadata and uptime workflows. It intentionally rejects address ranges and local hostnames.

Diagnostic privacy

Failed operations send sanitized diagnostic input, exceptions, and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL query strings are removed; reports are retained for 30 days. Exhausted upstream requests are reported once, not on each retry. Valid offline statuses are not error reports.

The Actor uses no AI models. Hostnames and ports are sent to the public mcsrvstat.us service; no player-identity expansion is performed. Run datasets and logs stay in Apify storage under your account's retention settings and can be deleted there; the Actor creates no separate persistent history. We operate and pay for the diagnostic service; no external account or supplier fee is required from you. Use the Actor's Apify Issues tab for support.

This is an independent automation-lab tool, not affiliated with or endorsed by Mojang, Microsoft, Minecraft, or mcsrvstat.us. Product names identify the compatible game and data source.

Troubleshooting

Why is a server marked offline when players can connect?

Confirm the hostname, port, and edition. Some servers block status pings or rely on DNS SRV records that take time to propagate. Inspect debugErrors, debugSrv, resolvedHostname, and resolvedPort.

Why are player names or software empty?

Those fields are optional and controlled by the target server. Player counts can be available while the sample list remains empty.

Why did I receive an error row?

The public status API timed out, returned a temporary error after retries, or returned an unexpected response. Review errorType, errorMessage, sourceUrl, and lookupMs, then retry later if appropriate.

Does this Actor support Bedrock?

Yes. Use an object with edition: "bedrock" and provide the server's hostname and optional port.

FAQ

Does the Actor require a Minecraft account?

No. It queries public status metadata without login credentials.

Can it scan an IP range for servers?

No. Supply known public DNS hostnames. Range and port scanning are deliberately out of scope.

Does it monitor continuously?

Each run produces a snapshot. Use an Apify schedule for recurrence and compare datasets in your own workflow.

Are offline rows charged?

Yes. A completed source-confirmed offline check is useful status data. HTTP/API request errors are exported but receive no per-status charge.

Can I set a maximum spend?

Yes. Configure the maximum total run charge in Apify and use the maximum status rows input to bound the batch.

Related automation-lab Actors

• PlayerDB Minecraft Profile Lookup resolves supplied Minecraft usernames and UUIDs into canonical player profiles and texture assets.

Use the profile Actor when your input is a player identity. Use this Actor when your input is a known server hostname.