Server Status API

How It Works

The template uses mcsrvstat.us, a free Minecraft server status API. No API key required. No account needed.

What It Provides

Configuration

serverStatus: {
  // Enable/disable status polling
  enabled: true,
  
  // How often to check (milliseconds)
  pollingInterval: 30000,  // 30 seconds
  
  // Display options
  showPlayerCount: true,
  showVersion: true,
  
  // Message when server is offline
  offlineText: 'Server Maintenance',
}

Polling Behavior

The status hook polls the API at regular intervals:

• ▸First check happens immediately on page load
• ▸Subsequent checks happen every pollingInterval
• ▸Failed requests retry with exponential backoff
• ▸Status cached in React state between polls

// In src/hooks/useServerStatus.ts
const fetchStatus = async () => {
  const response = await fetch(
    `https://api.mcsrvstat.us/2/${serverIp}`
  );
  const data = await response.json();
  return {
    online: data.online,
    players: data.players?.online || 0,
    maxPlayers: data.players?.max || 0,
    version: data.version,
  };
};

Rate Limits

Troubleshooting

Status shows offline but server is up

• ▸Check if your server IP is correct in config
• ▸Ensure your server allows status queries (query-port open)
• ▸Some hosts block status queries - check with your provider
• ▸Try the API directly in browser: api.mcsrvstat.us/2/your.ip

Player count not showing

• ▸Make sure showPlayerCount is true in config
• ▸Some server plugins hide player count
• ▸Bungeecord/Velocity may need additional setup

Disable status completely

// Option 1: Disable in config
serverStatus: {
  enabled: false,
  // ...
}

// Option 2: Hide the section entirely
sections: {
  serverStatus: false,
  // ...
}

Alternative APIs

If you need to use a different API, modify src/hooks/useServerStatus.ts. Other popular options: