Minecraft 服务器信息查询接口 — HTTP GET / UTF-8 JSON
| 说明 | 当前 API 版本为 v1，字段变更会向下兼容。如有破坏性变更将通过新版本路径提供。 | |
| Base URL | https://mca.umrc.cn | |
| 端点 | /api/query.php | |
| 请求方式 | GET | |
| 数据格式 | application/json; charset=utf-8 | |
| 域名绑定 | 仅接受 Host 头为 mca.umrc.cn 的请求 | |
| CORS | Access-Control-Allow-Origin: * | |
| 限流 | 单 IP 每分钟 120 次 | |
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
host |
string | 是 | 服务器地址。支持域名、IPv4、[::1] 格式 IPv6。默认端口 25565，可用 域名:端口 或 [IPv6]:端口 指定自定义端口，如 play.example.com:25566 |
示例中的 play.example.com 为占位地址，请替换为真实服务器域名或 IP。
方式一：浏览器直接访问
https://mca.umrc.cn/api/query.php?host=play.example.com浏览器直接打开即可查询，无需额外参数。
方式二：命令行
curl "https://mca.umrc.cn/api/query.php?host=play.example.com"频繁请求会触发限流（每分钟 120 次），请合理控制频率。
方式三：嵌入式组件
<script src="https://mca.umrc.cn/mcquery.js" host="play.example.com"></script>
<div mc-online></div>
<div mc-online mc-field="max"></div>
<div mc-online mc-field="latency"></div>支持的 mc-field 值：online、max、latency、version、motd、type
{
"success": true,
"data": {
"host": "play.example.com",
"port": 25565,
"version": "Paper 1.20.4",
"protocol": 765,
"players_online": 42,
"players_max": 100,
"player_sample": [
{ "name": "Steve", "id": "8667ba71-b85a-4004-9b54-0cceb1e2f1b6", "online_mode": true },
{ "name": "Alex", "id": "ca2b4b4c-1c3a-4a1a-8b2c-1e2f3a4b5c6d", "online_mode": true }
],
"motd": "<span style=\"color:#55FF55\">Welcome</span><span style=\"color:#FF5555\"> to my server!</span>",
"motd_plain": "Welcome to my server!",
"favicon": "iVBORw0KGgoAAAANS...",
"favicon_mime": "image/png",
"latency": 23.5,
"server_type": "Paper",
"modinfo": null,
"location": "广东"
},
"rate_limit": {
"remaining": 119
}
}| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 请求是否成功 |
data.host | string | 查询的服务器地址 |
data.port | int | 服务器端口 |
data.version | string | 服务器版本名称（如 Paper 1.20.4） |
data.protocol | int | 协议版本号 |
data.players_online | int | 当前在线人数 |
data.players_max | int | 最大玩家数 |
data.player_sample | array | 在线玩家样例。每个元素包含 name、id（UUID）、online_mode（true=正版/false=离线）。头像可通过 Cravatar 获取：正版玩家 https://cravatar.eu/avatar/{uuid去除横杠}/32.png，离线玩家 https://cravatar.eu/avatar/MHF_Steve/32.png。1.19+ 服务器可能不返回玩家列表，此时为空数组 |
data.motd | string | HTML 格式的服务器 MOTD（§ 颜色码和 JSON 格式均已转为 HTML span） |
data.motd_plain | string | 纯文本格式的 MOTD（去除所有颜色码和格式） |
data.server_type | string | 服务器类型。支持识别：Paper、Spigot、Purpur、BungeeCord、Waterfall、Velocity、Pufferfish、Folia、Forge、Vanilla |
data.favicon | string | Base64 编码的服务器图标（不含 data: 前缀） |
data.favicon_mime | string | 图标 MIME 类型（如 image/png），前端拼接 data:{mime};base64,{favicon} 使用 |
data.latency | float | TCP 往返延迟，单位 ms，精确到 0.1 |
data.modinfo | object/null | 模组信息。Forge 服务器返回 {"type":"FML","modList":[...]}，原版返回 null |
data.location | string/null | 服务器 IP 所在省份（通过 ip-api.com 查询），查询失败时为 null |
rate_limit.remaining | int | 本 IP 当前窗口剩余可用请求次数 |
| HTTP | 错误信息 | 触发条件 | 建议 |
|---|---|---|---|
400 | 请提供服务器地址 | 缺少 host 参数 | 检查参数，不重试 |
400 | 服务器地址格式无效 | host 不符合域名/IP 规范 | 修正格式，不重试 |
403 | 请求被拒绝：非法的域名来源 | Host 头不是 mca.umrc.cn | 检查请求目标域名 |
403 | 请求被拒绝：IP 不一致，疑似会话劫持 | 请求来源 IP 发生变化 | 检查网络环境 |
403 | 请求被拒绝：不支持的客户端 | User-Agent 被拦截 | 更换 UA，不重试 |
429 | 请求过于频繁 | 单 IP 超过每分钟 120 次 | 等待 retry_after 秒后重试 |
502 | 无法连接到服务器 | 目标 MC 服务器无响应或超时 | 检查服务器地址是否正确 |
API 仅接受 HTTP Host 头为 mca.umrc.cn 的请求。直接使用 IP 地址或其他域名访问将被 403 拒绝。CORS 已放开（Access-Control-Allow-Origin: *），允许任意来源的前端 JS 跨域调用，但请求目标必须是 mca.umrc.cn。
每 2 次请求校验一次客户端 IP 是否与之前记录一致。若 IP 变化，立即销毁 session 并返回 403。正常用户通过固定网络访问不受影响。
基于 IP 的滑动窗口限流：每分钟 120 次。超限后 IP 被临时封禁 300 秒。响应中返回 rate_limit.remaining 标识剩余次数，超限时附带 retry_after 秒数。
拦截常见爬虫工具的 User-Agent（wget、python-requests、Go-http-client、scrapy 等）。浏览器和标准 HTTP 客户端不受影响。
兼容阿里云 CDN、腾讯云 CDN、Cloudflare 等主流 CDN 的 IP 透传头，确保限流和 IP 对账基于真实客户端 IP。