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
Presentation	motdRaw, motdClean, motdHtml, 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.

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 objects. Each object has host, optional port, and edition set to java or bedrock.

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. The default is 20. Inputs after this 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. Invalid input fails closed before requests begin.

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.
• Source caching means repeated runs may receive the same underlying check.
• 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.

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.