MCP-MCSTATUS Server

You can run MCP-MCSTATUS as a local or remote MCP server to access Minecraft status, DNS, GeoIP, BGP, and Kuma node data through a single API surface and client integrations.

How to use

You integrate an MCP client that can call the available endpoints to fetch Minecraft status for Java and Bedrock, SRV records, DNS information, IP provider data, GeoIP lookups, and Kuma node status. The server exposes an MCP API that you can connect to via either a local stdio process or a streamable HTTP endpoint depending on your deployment needs. Use the provided tool names to request specific data such as get_minecraft_status, get_srv_records, or check_node_status to determine whether Kuma nodes are UP, DOWN, PENDING, or MAINTENANCE.

How to install

Install requires Python and a virtual environment. Create or activate a virtual environment, install dependencies, and prepare to run the server.

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

Additional sections

Configuration defaults are exposed via environment variables. You can customize API bases, timeouts, Kuma endpoints, and BGP tools data sources. The default MCP endpoint for local deployments is http://localhost:8000/mcp. You can run the server with the standard Python entry point and a virtual environment, or deploy via Docker Compose for a quick start.

Run with Docker Compose

Use Docker Compose to start the MCP server and its dependencies in detached mode. This builds the image if needed and runs the containers in the background.

docker compose up -d --build

Stop the services with:

docker compose down

## Run MCP Server

The default transport is stdio. Run the server by starting the Python entry point from the virtual environment.

.._venv\Scripts\python.exe main.py

If you want to use a different transport, set the environment variable MCP_TRANSPORT accordingly and restart the server.

Local Stdio Config Example

You can configure a local stdio MCP server in a JSON config that maps a server label to the Python command and the Python script to run.

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

Environment variables

The server relies on a collection of environment variables to control behavior, API endpoints, and data sources. You can configure transport, base URLs, timeouts, and various tools before starting the server.

Use With OpenAI

For OpenAI integration, expose a public HTTPS MCP endpoint and bind the MCP server to streamable HTTP or similar transport for remote use. Create a tool binding that exposes the available tools and points to the public MCP URL.

Notes and tips

Remember to supply necessary credentials or license keys if your GeoIP or BGP data sources require them. When running locally, you can test with the sample config and adjust the environment to point to your Kuma status page or DC endpoints.

Available tools

get_minecraft_status

Fetch Minecraft server status for Java and Bedrock using the /api/status endpoint.

get_java_status

Shortcut to retrieve Java server status via the same /api/status endpoint.

get_bedrock_status

Shortcut to retrieve Bedrock server status via the /api/status endpoint.

get_srv_records

Resolve SRV records for a domain via the /api/srv endpoint.

resolve_dns

Resolve DNS and provider information via the /api/dns endpoint.

rdns

Perform reverse DNS (PTR) lookups for an IP.

geoip_maxmind

Look up geolocation using a local MaxMind GeoLite2 database.

get_ip_provider_info

Fetch IP provider/operator information using bgp.tools whois and ASN database.

is_ip_anycast

Check if a player IP is Anycast by consulting a curated node list.

get_bgp_info

Retrieve BGP/ASN details for an IP via the /api/bgp endpoint.

check_node_status

Find a Kuma node by name or alias and return UP/DOWN/PENDING/MAINTENANCE status.