Minecraft 服务器状态 API

查询 Minecraft Java 版服务器状态

GET /api/mc/server

请求参数

• host（必填）：服务器地址（域名或公网 IP，可写成 host:port）；不允许内网和保留地址，示例 mc.hypixel.net
• port：端口，1024~65535。不传且 host 是域名时先查 SRV 记录（_minecraft._tcp.host），没有 SRV 再用 25565；传了就不查 SRV，示例 25565

返回字段

• host（string）：查询的主机（ASCII 形式，中文域名为 punycode）或 IP
• port（number）：实际连接的端口（用了 SRV 记录时为 SRV 指向的端口）
• ip（string|null）：实际连接的 IP；域名解析失败时为 null
• srv（object|null）：使用的 SRV 记录；没有 SRV 记录或显式指定了端口时为 null
• srv.target（string）：SRV 记录指向的主机
• srv.port（number）：SRV 记录指向的端口
• online（boolean）：是否在线（成功拿到状态信息）
• error（string|null）：离线原因的中文说明（如“连接被拒绝（端口未开放或服务未启动）”“查询超时”）；在线时为 null
• version（object|null）：服务器版本；离线时为 null
• version.name（string）：版本名（已去掉 § 格式代码），如“1.21.4”或代理服务器自定义的名称
• version.protocol（number|null）：协议号，如 769；服务器没给时为 null
• players（object|null）：玩家信息；离线时为 null
• players.online（number）：在线人数
• players.max（number）：人数上限
• players.sample（array）：服务器提供的在线玩家样例（最多 20 个）；很多服务器不提供或用它显示自定义文字
• players.sample[].name（string）：玩家名（已去掉 § 格式代码）
• players.sample[].id（string|null）：玩家 UUID；没给时为 null
• motd（object|null）：服务器描述（MOTD）；离线时为 null
• motd.text（string）：纯文本：JSON 聊天组件已展开拼接，§ 颜色 / 格式代码已去掉，每行首尾空白已去掉，多行用 \n 分隔
• motd.raw（string）：原始内容：服务器返回字符串时原样保留（含 § 代码）；返回 JSON 聊天组件时为该组件的 JSON 字符串
• favicon（string|null）：服务器图标（64×64 PNG 的 data URI，可直接用作 img 的 src）；没有图标时为 null
• latency（number|null）：Ping/Pong 往返延迟（毫秒，本服务器到目标服务器）；服务器不响应 Ping 或离线时为 null