MCP Mcstatus

MCP-MCSTATUS

MCP服务器（Python）及其相关工具 https://mcstatus.xyz/api 以及Kuma状态页API。

已实施的MCP工具

• get_minecraft_status -Minecraft服务器状态（Java/Bedrock），端点 /api/status
• get_java_status -Java状态快捷方式、端点 /api/status
• get_bedrock_status -基岩状态快捷方式、终点 /api/status
• get_srv_records -SRV记录，端点 /api/srv
• resolve_dns -DNS解析和提供商信息、端点 /api/dns
• rdns -IP的反向DNS（PTR）查找
• geoip_maxmind -使用本地MaxMind GeoLite2数据库进行GeoIP查找
• get_ip_provider_info -IP的提供商/运营商信息 bgp.tools whois+ASN数据库
• is_ip_anycast -按策划的已知节点列表检查玩家IP是否为Anycast
• get_bgp_info -IP端点的BGP/ASN详细信息 /api/bgp
• check_node_status -通过名称或短别名查找Kuma节点（例如。， s3, br4)并返回 UP/DOWN/PENDING/MAINTENANCE

check_node_status 对于GPT

当您需要通过人类友好的别名从Kuma获取节点状态时，请使用此工具。

输入参数：

• node_name (string，必填）-完整节点名称或短别名。
• timeout_ms (integer，可选，默认 4000，必须 > 0).

支持的别名模式：

• 全名： s3.joinserver.xyz
• 第一个点前的短主机名： s3 为了 s3.joinserver.xyz
• 从短名称中分割出的令牌 -, _，或空间： br4
• 不区分大小写的变体： BR4
• 规范化别名（回退匹配中忽略非字母数字字符）
• 解释了带有通用前缀的嘈杂别名： Node-x21, node x 21, Nodex21, Нода-x21 -> x21.oinserver.xyz
• 纯分隔别名也有效： x 21 -> x21.oinserver.xyz

状态映射：

• 1 -> UP
• 0 -> DOWN
• 2 -> PENDING
• 任何其他/未知-> MAINTENANCE

结果格式(ok = true):

{
  "ok": true,
  "input_node_name": "x 21",
  "interpreted_query": {
    "normalized": "x21",
    "core_parts": ["x", "21"],
    "core_fingerprint": "x21"
  },
  "node_name": "x21.oinserver.xyz",
  "node_id": 386,
  "matched_by": "short_hostname_normalized",
  "match_priority": 3,
  "status": "DOWN",
  "status_code": 0,
  "heartbeat_time": "2026-03-15 13:52:53",
  "message": "",
  "ping": null,
  "has_heartbeat": true,
  "matched_by_case_insensitive_name": true
}

结果格式(ok = false):

• 未找到：

{
  "ok": false,
  "input_node_name": "unknown",
  "interpreted_query": {
    "normalized": "unknown",
    "core_parts": ["unknown"],
    "core_fingerprint": "unknown"
  },
  "error": "Node with this name/alias was not found on Kuma status page."
}

• 宽泛或模糊的别名：

{
  "ok": true,
  "input_node_name": "fra",
  "interpreted_query": {
    "normalized": "fra",
    "core_parts": ["fra"],
    "core_fingerprint": "fra"
  },
  "ambiguous": true,
  "match_count": 2,
  "match_priority": 6,
  "matched_by_modes": ["core_terms_subset"],
  "matches": [
    {
      "node_name": "fra9.joinserver.xyz",
      "node_id": 245,
      "matched_by": "core_terms_subset",
      "match_priority": 6,
      "status": "UP",
      "status_code": 1
    },
    {
      "node_name": "MySQL-FRA9",
      "node_id": 290,
      "matched_by": "core_terms_subset",
      "match_priority": 6,
      "status": "UP",
      "status_code": 1
    }
  ]
}

GPT使用流程：

1. 尝试你拥有的最好的人绳： s3, br4, fra28, x 21, Node-x21.
2. 如果响应包含 matches，直接检查退回状态；广义查询现在返回所有最佳匹配。
3. 只有在需要单个精确节点时，才使用更具体的名称重试。

兼容性说明：

• MCP工具响应作为常规JSON有效载荷返回，因此FastMCP发出两个文本 content 和 structuredContent，这避免了忽略空的仅结构化回复的客户端中的“未返回结果”行为。

建筑

• mcstatus_mcp/client.py -类型化API客户端(MCStatusApiClient)
• mcstatus_mcp/tools.py -摘要 BaseMCStatusTool +每个MCP工具一个类
• mcstatus_mcp/server.py -MCP应用程序引导和工具注册

每个工具都作为一个类实现，该类继承自 BaseMCStatusTool. 所有工具都依赖于共享 MCStatusApiClient 例子

安装

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

使用Docker Compose运行

docker compose up -d --build

停止：

docker compose down

compose中的默认MCP端点：

http://localhost:8000/mcp

运行MCP服务器

默认传输方式为 stdio:

.\.venv\Scripts\python.exe main.py

可选传输覆盖：

$env:MCP_TRANSPORT="sse"
.\.venv\Scripts\python.exe main.py

允许 MCP_TRANSPORT 值： stdio, sse, streamable-http.

本地标准配置示例

{
  "mcpServers": {
    "mcstatus": {
      "command": "C:\\Users\\rakse\\PycharmProjects\\MCP-MCSTATUS\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\rakse\\PycharmProjects\\MCP-MCSTATUS\\main.py"]
    }
  }
}

环境变量

• MCP_TRANSPORT -MCP传输（默认值： stdio)
• MCSTATUS_API_BASE_URL -API基本URL（默认值： https://mcstatus.xyz/api)
• KUMA_API_BASE_URL -的Kuma API基础URL check_node_status （默认值： http://status.dsts.cloud:3001/api)
• MCSTATUS_TIMEOUT_MS -工具的默认超时时间（毫秒）（默认值： 4000)
• MCP_HOST -HTTP传输主机(sse 和 streamable-http，默认值： 127.0.0.1)
• MCP_PORT -HTTP传输端口（默认值： 8000)
• MCP_STREAMABLE_HTTP_PATH -可流式传输的HTTP路径（默认值： /mcp)
• MCP_SSE_PATH -SSE路径（默认值： /sse)
• MAXMIND_LICENSE_KEY -用于下载GeoLite2的MaxMind许可证密钥（如果数据库丢失/过时，则需要自动下载）
• MAXMIND_DB_PATH -本地路径 .mmdb 文件（默认值： data/GeoLite2-City.mmdb)
• MAXMIND_EDITION_ID -MaxMind版本ID（默认值： GeoLite2-City)
• MAXMIND_REFRESH_HOURS -数据库刷新间隔（小时）； 0 禁用定期刷新（默认值： 24)
• BGPTOOLS_USER_AGENT -带有下载联系人的描述性用户代理 https://bgp.tools/asns.csv （推荐）
• BGPTOOLS_ASN_DB_URL -ASN CSV源URL（默认值： https://bgp.tools/asns.csv)
• BGPTOOLS_ASN_DB_PATH -ASN CSV缓存的本地路径（默认： data/bgp_tools_asns.csv)
• BGPTOOLS_ASN_REFRESH_HOURS -ASN CSV刷新间隔（小时）； 0 禁用定期刷新（默认值： 24)
• BGPTOOLS_WHOIS_HOST -bgp.tools主机（默认： bgp.tools)
• BGPTOOLS_WHOIS_PORT -bgp.tools whois端口（默认： 43)

使用OpenAI

重要提示：OpenAI MCP集成使用远程MCP服务器。 本地 stdio 服务器适合本地开发/测试，但对于OpenAI绑定，您应该公开一个公共HTTPS端点。

1） 以流式HTTP运行以进行部署

$env:MCP_TRANSPORT="streamable-http"
$env:MCP_HOST="0.0.0.0"
$env:MCP_PORT="8000"
.\.venv\Scripts\python.exe main.py

部署后，您的MCP URL将如下所示：

https://your-domain.example/mcp

2） 在OpenAI响应API中绑定MCP服务器

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "mcstatus",
            "server_url": "https://your-domain.example/mcp",
            "require_approval": "never",
            "allowed_tools": [
                "get_minecraft_status",
                "get_java_status",
                "get_bedrock_status",
                "get_srv_records",
                "resolve_dns",
                "rdns",
                "geoip_maxmind",
                "get_ip_provider_info",
                "is_ip_anycast",
                "get_bgp_info",
                "check_node_status",
            ],
        }
    ],
    input="Check DNS and Java status for mc.hypixel.net",
)

print(response.output_text)

3） ChatGPT中的绑定（连接器）

• 打开ChatGPT连接器设置。
• 使用远程MCP URL添加自定义连接器。
• 选择工具和权限。

参考文件：

• https://platform.openai.com/docs/guides/tools-remote-mcp
• https://platform.openai.com/docs/guides/mcp
• https://help.openai.com/en/articles/11487775-connectors-in-chatgpt/