游戏

查询 MC 服务器

0次调用

1 积分/次

想在加入服务器前看看有多少人在线？或者检查一下服务器开没开？用这个接口就对了！

GET

uapis.cn

/api/v1/game/minecraft/serverstatus

查询参数

server

string

required

Minecraft服务器的地址，可以是域名（如 hypixel.net）或 IP:端口 的形式（如 mc.example.com:25565）。如果省略端口，将默认使用 25565。

功能概述

你可以通过提供服务器地址（域名或IP），来获取一个 Minecraft Java 版服务器的实时状态。返回信息包括服务器是否在线、当前玩家数、最大玩家数、服务器版本、MOTD（每日消息）以及服务器图标等。

如果服务器返回当前在线玩家列表，响应里还会带上 online_players 字段。这个字段可能省略，部分服务器返回的列表也可能不完整。

查询参数

server

string必填

Minecraft服务器的地址，可以是域名（如 hypixel.net）或 IP:端口 的形式（如 mc.example.com:25565）。如果省略端口，将默认使用 25565。

名称	类型	属性	说明
`server`	string	必填	Minecraft服务器的地址，可以是域名（如 `hypixel.net`）或 `IP:端口` 的形式（如 `mc.example.com:25565`）。如果省略端口，将默认使用 `25565`。

响应

200 / 请求成功

查询成功！返回服务器的详细状态信息。

JSON

{
  // 服务器图标的 Base64 Data URI。你可以直接在 `<img>` 标签的 `src` 属性中使用它。
  "favicon_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACayAAACqaXHeAAAA...",
  // 服务器解析后的IP地址。
  "ip": "172.65.252.238",
  // 服务器配置的最大玩家容量。
  "max_players": 20000,
  // 纯文本格式的服务器MOTD（每日消息），去除了所有颜色和格式代码。
  "motd_clean": "Hypixel Network [1.8-1.20]\n                                      SKYBLOCK",
  // HTML格式的服务器MOTD，保留了颜色和样式，方便你在网页上直接渲染。
  "motd_html": "<span style=\"color: #ffff55\"><b>Hypixel Network </b></span><span style=\"color: #555555\">[</span><span style=\"color: #aaaaaa\">1.8-1.20</span><span style=\"color: #555555\">]</span><br /><span style=\"color: #ffffff\">                                      </span><span style=\"color: #55ff55\"><b>SKYBLOCK</b></span>",
  // 服务器当前是否在线。
  "online": true,
  // 当前在线玩家列表。如果服务器没有返回这个字段，它会省略。部分服务器返回的列表可能不完整。
  "online_players": [
    {
      // 玩家名称。
      "name": "Steve",
      // 玩家的 UUID。部分服务器可能不返回这个字段。
      "uuid": "00000000-0000-0000-0000-000000000001"
    }
  ],
  // 当前在线的玩家数量。
  "players": 45321,
  // 服务器使用的端口。
  "port": 25565,
  // 服务器报告的版本信息。
  "version": "Requires 1.8-1.20"
}

400 / 错误的请求

请求失败。请检查你是否提供了 server 参数。

JSON

{
  "code": "INVALID_ARGUMENT",
  "details": {},
  "message": "Missing 'server' parameter."
}

404 / 未找到

服务器未找到。这可能意味着你提供的服务器地址无法解析，或者服务器当前处于离线状态。

JSON

{
  "code": "NOT_FOUND",
  "details": {},
  "message": "Server not found or is offline."
}

502 / 网关错误

查询失败。在尝试连接并获取服务器信息时发生网络错误或协议错误。

JSON

{
  "code": "UPSTREAM_ERROR",
  "details": {},
  "message": "Failed to query server status."
}

快速上手

选择你的语言查看调用示例

认证方式：

cURL 命令

curl 'https://uapis.cn/api/v1/game/minecraft/serverstatus?server=play.minedhype.com'

常见问题解答