Minecraft-MP APIminecraft-mp.com ↗
Access Minecraft server rankings, player counts, uptime history, vote leaderboards, and geo-latency data from minecraft-mp.com via 9 structured endpoints.
What is the Minecraft-MP API?
This API exposes 9 endpoints covering the full breadth of minecraft-mp.com server data, from paginated rank lists to per-server statistics, vote leaderboards, and multi-region ping measurements. The get_server_details endpoint returns fields including MOTD, uptime percentage, current and max players, server location, and Minecraft version for any server ID. Combined with get_server_statistics, developers can pull historical time-series data across daily, weekly, and monthly windows.
curl -X GET 'https://api.parse.bot/scraper/23972168-4a6b-41a8-b887-cf688fc2077c/get_server_list?page=1' \ -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 minecraft-mp-com-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.
from parse_apis.minecraft_mp_server_list_api import MinecraftMP, Period, ListType, FilterCategory, FilterType
client = MinecraftMP()
# List top-ranked servers with pagination
for server in client.servers.list(limit=5):
print(server.name, server.rank, server.address, server.status)
print(server.players.current, server.players.max)
# Get detailed info for a specific server
detail = client.servers.get(server_id="179012")
print(detail.name, detail.server_id)
# Get historical statistics for that server
stats = detail.statistics.get(period=Period.DAILY)
print(stats.period, stats.server_id)
# List voters for the server
for voter in detail.voters.list(limit=10):
print(voter.nickname, voter.votes)
# Get ping measurements
for ping in detail.pings.list(limit=5):
print(ping.location, ping.latency, ping.pinged)
# Search servers by keyword
for srv in client.servers.search(keyword="survival", limit=10):
print(srv.name, srv.version, srv.address)
# Get special list of latest servers
for srv in client.servers.special(list_type=ListType.LATEST, limit=5):
print(srv.name, srv.rank)
# Browse available country filters
for flt in client.filters.list(filter_type=FilterCategory.COUNTRIES, limit=10):
print(flt.name, flt.slug, flt.count)
# Get servers filtered by country
for srv in client.servers.by_filter(filter_type=FilterType.COUNTRY, slug="united-states-of-america", limit=5):
print(srv.name, srv.rank, srv.address)
Get the main paginated list of Minecraft servers ranked by popularity. Returns 25 servers per page with basic info (rank, name, address, version, players, status).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"servers": "array of server summary objects with server_id, rank, name, address, version, players, status, and tags",
"last_page": "integer, last available page number"
},
"sample": {
"data": {
"page": 1,
"servers": [
{
"name": "EarthMC",
"rank": "1",
"tags": [],
"status": "Online",
"address": "mp.earthmc.net",
"players": {
"max": "800",
"current": "503"
},
"version": "26.1.2",
"server_id": "332214"
}
],
"last_page": 354
},
"status": "success"
}
}About the Minecraft-MP API
Server Discovery and Filtering
get_server_list returns 25 servers per page ordered by popularity rank, with each entry carrying server_id, rank, name, address, version, players, status, and tags. For targeted queries, search_servers accepts keyword, version (e.g. 1.21.1), country slug, theme, and comma-separated tags, and returns the same summary shape plus the echoed query object. get_filtered_list drills further using slugs from get_filters — note that version slugs replace dots with underscores (1_21_1), while country slugs use hyphens (united-states-of-america). get_filters itself covers four categories: countries, versions, types, and themes, each returning name, slug, and count.
Per-Server Detail and History
get_server_details returns the full metadata record for a single server: name, rank, uptime, players as a current/max string, location, server_id, and minecraft_version. For longitudinal analysis, get_server_statistics accepts a period parameter (daily, weekly, or monthly) and returns four sub-objects — players, uptime, rank, and votes — each containing parallel labels (date strings) and data (numeric values) arrays suitable for charting.
Votes and Latency
get_server_vote_page returns the monthly vote leaderboard for a server as an array of voter objects with nickname and votes fields. get_server_ping returns an array of pings objects, each with location, latency, and pinged (timestamp of last check), giving a snapshot of global reachability from multiple geographic regions.
Special Lists
get_special_list provides four curated views of the server index: latest (recently added), updated (recently updated), random (non-paginated random sample), and most-played (sorted by active player count). All list endpoints share the same server summary object shape, making it straightforward to integrate multiple list types into a single consumer.
The Minecraft-MP API is a managed, monitored endpoint for minecraft-mp.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when minecraft-mp.com 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 minecraft-mp.com 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?+
- Track rank and player-count trends for a Minecraft server over time using
get_server_statisticswith weekly or monthly periods. - Build a server browser filtered by game version and country using slugs from
get_filterspassed toget_filtered_list. - Monitor uptime percentage and current player counts across a watchlist of servers via
get_server_details. - Display a monthly top-voter leaderboard on a server's community site using
get_server_vote_page. - Identify the lowest-latency Minecraft server for a given region by comparing
latencyvalues fromget_server_ping. - Aggregate newly listed servers for a discovery feed using
get_special_listwithlist_typeset tolatest. - Power a tag-based server search interface using the
tagsandkeywordparameters insearch_servers.
| 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 minecraft-mp.com offer an official developer API?+
What does get_server_statistics return and how granular is the data?+
players, uptime, rank, and votes — each with a labels array of date strings and a data array of corresponding numeric values. The period parameter accepts daily, weekly, or monthly, which controls the resolution and time window of the returned arrays.Does get_server_ping return real-time latency or cached results?+
pinged field indicating when the measurement was last taken, so results reflect the most recently recorded check rather than a live measurement at request time. Freshness varies per server and per location.Can I retrieve player reviews or comments for a server?+
Does search_servers support sorting by fields other than rank?+
orderby parameter accepts a sort field; omitting it defaults to rank. The accepted values for orderby beyond rank are not enumerated in the response schema. The API currently does not document discrete sort options beyond the default. You can fork it on Parse and revise the endpoint to expose and validate the full set of supported sort values.