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)

Status mapping:

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

Result format (ok = true):

{
  "ok": true,
  "input_node_name": "s3",
  "node_name": "s3.joinserver.xyz",
  "node_id": 124,
  "matched_by": "short_hostname",
  "status": "DOWN",
  "status_code": 0,
  "heartbeat_time": "2026-02-19 11:48:48",
  "message": "",
  "ping": null,
  "has_heartbeat": true,
  "matched_by_case_insensitive_name": true
}

Result format (ok = false):

• not found:

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

• ambiguous alias:

{
  "ok": false,
  "input_node_name": "hmfra1",
  "error": "Multiple nodes matched this name/alias at the same confidence level. Use a more specific node name.",
  "matches": [{"id": 305, "name": "HMFRA1-7950"}, {"id": 304, "name": "HMFRA1-R9"}]
}

GPT usage flow:

1. Try short alias first (s3, br4, fra28).
2. If ambiguous, retry with a more specific name from matches.
3. If not found, retry with full node name.

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\\PycharmProjects\\MCP-MCSTATUS\\main.py"]
    }
  }
}

Environment Variables

• MCP_TRANSPORT - MCP transport (default: stdio)
• MCSTATUS_API_BASE_URL - API base URL (default: https://mcstatus.xyz/api)
• KUMA_API_BASE_URL - Kuma API base URL for check_node_status (default: http://status.dsts.cloud:3001/api)
• MCSTATUS_TIMEOUT_MS - default timeout in milliseconds for tools (default: 4000)
• MCP_HOST - host for HTTP transports (sse and streamable-http, default: 127.0.0.1)
• MCP_PORT - port for HTTP transports (default: 8000)
• MCP_STREAMABLE_HTTP_PATH - streamable HTTP path (default: /mcp)
• MCP_SSE_PATH - SSE path (default: /sse)
• MAXMIND_LICENSE_KEY - MaxMind license key for GeoLite2 download (required for auto-download if DB is missing/outdated)
• MAXMIND_DB_PATH - local path to .mmdb file (default: data/GeoLite2-City.mmdb)
• MAXMIND_EDITION_ID - MaxMind edition ID (default: GeoLite2-City)
• MAXMIND_REFRESH_HOURS - database refresh interval in hours; 0 disables periodic refresh (default: 24)
• BGPTOOLS_USER_AGENT - descriptive user-agent with contact for downloading https://bgp.tools/asns.csv (recommended)
• BGPTOOLS_ASN_DB_URL - ASN CSV source URL (default: https://bgp.tools/asns.csv)
• BGPTOOLS_ASN_DB_PATH - local path to ASN CSV cache (default: data/bgp_tools_asns.csv)
• BGPTOOLS_ASN_REFRESH_HOURS - ASN CSV refresh interval in hours; 0 disables periodic refresh (default: 24)
• BGPTOOLS_WHOIS_HOST - bgp.tools whois host (default: bgp.tools)
• BGPTOOLS_WHOIS_PORT - bgp.tools whois port (default: 43)

Use With OpenAI

Important: OpenAI MCP integration uses remote MCP servers. Local stdio servers are good for local dev/testing, but for OpenAI binding you should expose a public HTTPS endpoint.

1) Run as streamable HTTP for deployment

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

After deployment your MCP URL will look like:

https://your-domain.example/mcp

2) Bind MCP server in OpenAI Responses API

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) Bind in ChatGPT (Connectors)

• Open ChatGPT connector settings.
• Add a custom connector using your remote MCP URL.
• Select tools and permissions.

Reference docs:

• 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/