MCP-MCSTATUS MCP Server

MCP-MCSTATUS

MCP server (Python) with tools for https://mcstatus.xyz/api and Kuma status-page API.

Implemented MCP Tools

• get_minecraft_status - Minecraft server status (Java/Bedrock), endpoint /api/status
• get_java_status - Java status shortcut, endpoint /api/status
• get_bedrock_status - Bedrock status shortcut, endpoint /api/status
• get_srv_records - SRV records, endpoint /api/srv
• resolve_dns - DNS resolution and provider info, endpoint /api/dns
• rdns - reverse DNS (PTR) lookup for IP
• geoip_maxmind - GeoIP lookup using local MaxMind GeoLite2 database
• get_ip_provider_info - provider/operator info for IP via bgp.tools whois + ASN database
• is_ip_anycast - check if player IP is Anycast by curated known-node list
• get_bgp_info - BGP/ASN details for an IP, endpoint /api/bgp
• check_node_status - find Kuma node by name or short alias (e.g., s3, br4) and return UP/DOWN/PENDING/MAINTENANCE

`check_node_status` For GPT

Use this tool when you need node state from Kuma by human-friendly alias.

Input parameters:

• node_name (string, required) - full node name or short alias.
• timeout_ms (integer, optional, default 4000, must be > 0).

Supported alias patterns:

• full name: s3.joinserver.xyz
• short hostname before first dot: s3 for s3.joinserver.xyz
• token from short name split by -, _, or space: br4
• case-insensitive variants: BR4
• normalized alias (non-alphanumeric chars ignored in fallback matching)
• interpreted noisy aliases with generic prefixes: Node-x21, node x 21, Nodex21, Нода-x21 -> x21.oinserver.xyz
• plain separated aliases also work: x 21 -> x21.oinserver.xyz

Status mapping:

• 1 -> UP
• 0 -> DOWN
• 2 -> PENDING
• any other/unknown -> MAINTENANCE

Result format (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
}

Result format (ok = false):

• not found:

{
  "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."
}

• broad or ambiguous alias:

{
  "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 usage flow:

1. Try the best human string you have: s3, br4, fra28, x 21, Node-x21.
2. If response contains matches, inspect returned statuses directly; broad queries now return all best matches.
3. Only retry with a more specific name when you need a single exact node.

Compatibility note:

• MCP tool responses are returned as regular JSON payloads so FastMCP emits both text content and structuredContent, which avoids "returned no result" behavior in clients that ignore empty structured-only replies.

Architecture

• mcstatus_mcp/client.py - typed API client (MCStatusApiClient)
• mcstatus_mcp/tools.py - abstract BaseMCStatusTool + one class per MCP tool
• mcstatus_mcp/server.py - MCP app bootstrap and tool registration

Each tool is implemented as a class that inherits from BaseMCStatusTool. All tools depend on a shared MCStatusApiClient instance.

Install

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

Run With Docker Compose

docker compose up -d --build

Stop:

docker compose down

Default MCP endpoint from compose:

http://localhost:8000/mcp

Run MCP Server

Default transport is stdio:

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

Optional transport override:

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

Allowed MCP_TRANSPORT values: stdio, sse, streamable-http.

Local Stdio Config Example

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