minecraftservers APIminecraftservers.org ↗
Search, list, and retrieve detailed Minecraft server data including real-time player counts, uptime, vote history, and rankings from minecraftservers.org.
What is the minecraftservers API?
The minecraftservers.org API exposes 3 endpoints that cover server discovery, ranked listings, and per-server detail records. Use search_servers to query by name or keyword and get back IP addresses, online status, and live player counts. Use get_server_details to pull 9+ fields for a specific server including uptime percentage, vote totals, country, and historical player and vote data.
curl -X GET 'https://api.parse.bot/scraper/bb77c61d-ba0a-42c2-9c34-a3e2f8e97e59/search_servers?query=survival' \ -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 minecraftservers-org-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_servers_api import MinecraftServers, ServerSummary
client = MinecraftServers()
# Search for survival servers
for server in client.serversummaries.search(query="survival"):
print(server.name, server.ip, server.current_players, server.status)
# Get detailed info for a specific server
details = client.servers.get(id="400198")
print(details.name, details.players, details.uptime, details.votes, details.country)
# Navigate from a summary to full details
summary = client.serversummary("400198")
full = summary.details()
print(full.java_ip, full.owner, full.version)
# Browse top servers from page 1
for top in client.serversummaries.list(page=1):
print(top.name, top.ip, top.status)
Full-text search for Minecraft servers by name or keyword. Returns matching servers with basic info including IP, online status, and current player counts. Results are not paginated; a single request returns all matches.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword to find servers (e.g. 'survival', 'hypixel', 'skyblock'). |
{
"type": "object",
"fields": {
"query": "string — the search term used",
"results": "array of server objects with id, name, ip, status, current_players, url"
},
"sample": {
"data": {
"query": "survival",
"results": [
{
"id": "400198",
"ip": "hub.opblocks.com",
"url": "https://minecraftservers.org/server/400198",
"name": "OPBlocks",
"status": "online",
"current_players": "8023/8500"
}
]
},
"status": "success"
}
}About the minecraftservers API
Endpoints and Data Coverage
The API provides three endpoints that mirror the core workflows on minecraftservers.org. search_servers accepts a query string — terms like survival, skyblock, or a specific server name — and returns an array of matching server objects each containing id, name, ip, status, current_players, and a url back to the listing. Results are not paginated; all matches come back in a single response.
Ranked Listings and Pagination
list_servers returns up to 20 servers per page ranked by popularity. Pass an integer page parameter to walk through the list. Each page includes a pagination array with labeled page link objects so you can enumerate the full ranked set programmatically. The response shape is the same as search_servers results, giving you id, name, ip, status, current_players, and url per entry.
Per-Server Detail
get_server_details takes a server_id obtained from either listing endpoint and returns the fullest record available: owner, country, java_ip, players as a current/max string (e.g. 4389/4500), votes, uptime percentage, status, and a stats object containing player_history, vote_history, and daily_stats arrays. This historical data is useful for tracking growth trends or evaluating a server's community health over time.
The minecraftservers API is a managed, monitored endpoint for minecraftservers.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when minecraftservers.org 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 minecraftservers.org 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?+
- Build a Minecraft server finder app filtered by keyword, showing live
current_playersandstatusfromsearch_servers. - Track popularity trends for specific servers using
player_historyanddaily_statsfromget_server_details. - Aggregate the top-ranked servers from
list_serversinto a custom leaderboard sorted by player count. - Monitor server uptime over time by polling
uptimeandstatusfields fromget_server_details. - Compare vote counts across servers by collecting
votesdata from multipleget_server_detailscalls. - Enrich a Minecraft community site with server metadata — IP, country, owner, and max capacity — pulled from
get_server_details. - Alert users when a tracked server goes offline by watching the
statusfield returned byget_server_details.
| 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 minecraftservers.org have an official developer API?+
What does `get_server_details` return that the listing endpoints don't?+
get_server_details adds fields not present in search_servers or list_servers: owner, country, java_ip, votes, uptime, and the stats object containing player_history, vote_history, and daily_stats arrays. The listing endpoints return a smaller record focused on discovery — id, name, ip, status, current_players, and url only.Does `search_servers` support filtering by game mode, version, or region?+
search_servers accepts a single query string and returns all text-matched results without additional filter parameters. Country data is available in get_server_details once you have a server ID. You can fork this API on Parse and revise it to add filter parameters for region, version, or game mode.How is pagination handled in `list_servers`?+
list_servers returns up to 20 servers per page. The response includes a pagination array of page link objects with label and url fields. Pass an integer to the page parameter to retrieve subsequent pages. The total server count is not returned directly in the response.Does the API cover Bedrock edition server details or only Java edition?+
get_server_details response exposes a java_ip field. Bedrock-specific IP or port fields are not currently part of the response schema. You can fork this API on Parse and revise it to surface Bedrock edition data if the source listing includes it.