Minecraft 服务器查询 API 文档 - 我的世界服务器状态接口

基础信息

说明	当前 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	是	服务器地址。支持域名（含中文域名等国际化域名 IDN）、IPv4、IPv6。默认端口 25565，可用 `域名:端口` 或 `[IPv6]:端口` 指定自定义端口，如 `play.example.com:25566`、`中文域名.com`、`[2001:db8::1]:25566`。中文域名会先转换为 ASCII（Punycode）再查询，响应中的 `data.host` 仍返回原始输入。IPv6 推荐使用方括号写法 `[::1]`，裸 IPv6（如 `2001:db8::1`）仅在默认端口 25565 下有效，带自定义端口时必须写成 `[IPv6]:端口`

请求示例

示例中的 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-3a1a-8b2c-1e2f3a4b5c6d", "online_mode": false }
        ],
        "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（bool）。online_mode 依据 UUID 的版本位推断：版本位为 4（Mojang 正版 UUID）返回 `true`，版本位为 3（离线模式 UUID）返回 `false`，占位或非标准 UUID 同样返回 `false`。头像可通过 Minotar 获取（支持用户名或 UUID，UUID 可带或不带横杠）：正版玩家 `https://minotar.net/avatar/{uuid去除横杠}/32.png`，离线玩家 `https://minotar.net/avatar/MHF_Steve/32.png`（离线 UUID 取不到真实皮肤，前端统一使用 Steve 默认头像）。前端在 Minotar 不可用时会回退到 `https://crafatar.com/avatars/{uuid}?size=32`。1.19+ 服务器可能不返回玩家列表，此时为空数组
`data.motd`	string	HTML 格式的服务器 MOTD（§ 颜色码和 JSON 格式均已转为 HTML span）
`data.motd_plain`	string	纯文本格式的 MOTD（去除所有颜色码和格式）
`data.server_type`	string	服务器类型，由版本名称与 modinfo 字段推断。可识别：Paper、Spigot、Purpur、Pufferfish、Folia、Leaves、Gale、Velocity、Waterfall、BungeeCord、Travertine、FlameCord、Mohist、Magma、Arclight、CatServer、Thermos、Kettle、Banner、NeoForge、Forge、Fabric、Quilt、Proxy、Vanilla。版本名称中带有 proxy 但无法确定具体代理端时返回 `Proxy`；自研或闭源服务端（如 Hypixel）不对外暴露服务端标识，会返回 `Vanilla`
`data.favicon`	string	Base64 编码的服务器图标（不含 data: 前缀）
`data.favicon_mime`	string	图标 MIME 类型（如 image/png），前端拼接 `data:{mime};base64,{favicon}` 使用
`data.latency`	float	API 节点到目标服务器的 TCP 往返延迟，由 Minecraft SLP 协议的 Ping/Pong 数据包实测，单位 ms，精确到 0.1。该值反映 API 节点与目标服务器之间的网络质量，不是访问者本机到目标服务器的延迟；返回 0 表示目标服务器未回应该探测包，此时延迟不可用
`data.modinfo`	object/null	模组信息。Forge 服务器返回 `{"type":"FML","modList":[...]}`，原版返回 null
`data.location`	string/null	接入位置：本次查询实际连接到的对端 IP 的归属地（通过 ip-api.com 查询，IPv4 与 IPv6 均支持）。国内 IP 只返回省份（如 `浙江`），境外及港澳台 IP 返回 `国家/地区 · 省份`（如 `中国香港 · 東區`、`德国 · 巴登-符腾堡`）。注意这是入口节点（机房、CDN 或中转服务器）的归属地，不等同于服务器的实际所在地；查询失败时为 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 服务器无响应或超时	检查服务器地址是否正确

安全机制

1. 域名强绑定

API 仅接受 HTTP Host 头为 mca.umrc.cn 的请求。直接使用 IP 地址或其他域名访问将被 403 拒绝。CORS 已放开（Access-Control-Allow-Origin: *），允许任意来源的前端 JS 跨域调用，但请求目标必须是 mca.umrc.cn。

2. IP 对账防劫持

每 2 次请求校验一次客户端 IP 是否与之前记录一致。若 IP 变化，立即销毁 session 并返回 403。正常用户通过固定网络访问不受影响。

3. 请求限流

基于 IP 的滑动窗口限流：每分钟 120 次。超限后 IP 被临时封禁 300 秒。响应中返回 rate_limit.remaining 标识剩余次数，超限时附带 retry_after 秒数。

4. 客户端过滤

拦截常见爬虫工具的 User-Agent（wget、python-requests、Go-http-client、scrapy 等）。浏览器和标准 HTTP 客户端不受影响。

5. CDN 适配

兼容阿里云 CDN、腾讯云 CDN、Cloudflare 等主流 CDN 的 IP 透传头，确保限流和 IP 对账基于真实客户端 IP。

注意事项

仅支持 Java 版服务器（TCP Server List Ping 协议），基岩版（UDP/RakNet）无法查询，会返回 502
高版本服务器（1.19+）可能不返回在线玩家列表，player_sample 此时为空数组
服务器图标以 Base64 返回，前端用 data:{mime};base64,{favicon} 渲染
MOTD 同时支持传统 § 颜色码和 1.19+ JSON 格式，自动转换为 HTML
支持中文域名等国际化域名（IDN）：输入原样填写中文域名即可，服务端会转换为 ASCII（Punycode）后查询
SRV 记录自动解析：端口为 25565 时会查询 _minecraft._tcp DNS SRV 记录；返回多条记录时按优先级排序，连接失败会自动尝试下一条（最多 3 条）
IPv6 地址推荐使用 [IPv6] 或 [IPv6]:端口 写法，裸 IPv6 仅在默认端口下有效
latency 为 API 节点到目标服务器的往返延迟，返回 0 表示目标服务器未回应 Ping 包，延迟不可用
server_type 为启发式推断结果，不对外暴露服务端标识的服务器会返回 Vanilla
online_mode 依据 UUID 版本位推断，基岩版互通或插件自定义 UUID 可能被判定为离线
地理位置数据来源于 ip-api.com：国内 IP 返回省份，境外及港澳台 IP 返回「国家/地区 · 省份」。该位置是查询节点实际连接到的入口 IP 的归属地，走机房、CDN 或中转的服务器显示的是入口节点位置
禁止利用本 API 进行大规模爬取、商业转售或其他未经授权的用途

更新日志

v1.2 — 支持中文域名等国际化域名（IDN）：host 允许非 ASCII 字符，服务端用 intl（idn_to_ascii）或内置 RFC 3492 Punycode 实现转换为 ASCII 后查询，响应 data.host 保持原始输入；SRV 多条记录按 RFC 2782 优先级/权重排序，连接失败会自动尝试下一条（最多 3 条），修复部分服务器"另有一条 SRV 目标可用却报 502"的问题；修复玩家头像服务：原 cravatar.eu 已不可用（全站返回 503）导致头像全部加载失败，改用 minotar.net 并增加 crafatar.com 失败回退；location 改为按实际连接到的对端 IP 查询（此前用 DNS 首条 A 记录，多 A 记录域名可能查错机器），境外及港澳台 IP 返回「国家/地区 · 省份」，前端标签改为「接入位置」并加了说明。
v1.1 — 修复 latency 测量：改为在 Ping 与 Pong 数据包之间计时，返回真实往返延迟，未收到 Pong 时返回 0；修复 IPv6 地址的连接与地理位置查询，支持 [IPv6]、[IPv6]:端口 与裸 IPv6（默认端口），并校验端口范围 1-65535；player_sample[].online_mode 改为布尔值，并按 UUID 版本位区分正版（版本 4）与离线（版本 3）；server_type 扩充识别范围，新增 NeoForge、Fabric、Quilt、Proxy 及常用混合端，代理端不再被误判为 Forge；location 改用 SRV 解析后的真实目标地址查询。
v1.0 — 初始版本：支持 MOTD、在线人数、版本、协议、图标与地理位置查询。

联系与支持

官网：https://umrca.com
域名：https://mca.umrc.cn