MCStat-Plugin

MCStat - Minecraft Server Analytics Plugin

MCStat connects your Minecraft server or proxy to MCStat.org with secure, signed HTTPS telemetry.

It gives server owners more accurate analytics than public ping data alone: live player counts, player sessions, tracked playtime, uptime, TPS where supported, join/leave events, and dashboard-ready server activity.

Supported Platforms

MCStat provides separate jars for each platform family:

• Bukkit / Spigot / Paper / Purpur / Pufferfish / Folia
• Velocity 3.x
• BungeeCord / Waterfall
• Bukkit-compatible hybrid servers such as Mohist, Arclight, Magma, CatServer

Pure Fabric, Forge, NeoForge, Quilt, or Sponge servers need a native adapter unless they run a Bukkit-compatible layer.

Features

• Live online player count and max player count
• Signed server heartbeats
• Player UUID and player name tracking
• Join and leave event tracking
• Session start time and total playtime tracking
• TPS reporting on Bukkit-family servers
• Proxy support for Velocity and BungeeCord networks
• Retry queue for temporary network/API outages
• /vote command with MCStat server vote link
• Safe update checks through GitHub Releases
• No chat, inventory, private command, world data, or player IP collection

Privacy

MCStat only sends operational telemetry needed for server analytics and public status pages.

The plugin does not collect:

• Chat messages
• Private commands
• Inventories
• World data
• Player IP addresses

Telemetry is sent to https://mcstat.org over HTTPS using your server API key and local installation ID.

Installation

1. Download the jar matching your platform.
2. Put the jar in your server or proxy /plugins folder.
3. Restart the server or proxy.
4. Open the generated MCStat config file.
5. Paste your server API key from the MCStat dashboard.
6. Run /mcstat reload.
7. Verify the connection with /mcstat status.

Configuration

Example Bukkit/Spigot/Paper config:

api-key: "YOUR_API_KEY_HERE"
api-base-url: "https://mcstat.org"

sync-interval: 90

metrics:
  tps: true
  player-count: true
  player-names: true
  player-playtime: true
  player-events: true

updates:
  check: true
  notify-admins: true
  auto-download: false
  check-interval-hours: 24

Config Reference

Commands

Safe Updates

MCStat can check for updates automatically through official GitHub Releases.

By default:

updates:
  check: true
  notify-admins: true
  auto-download: false

The plugin never hot-swaps or replaces a running jar. If download is enabled or /mcstat update download is used, the new jar is staged in the plugin data folder under updates/.

To install a downloaded update:

1. Stop the server or proxy.
2. Replace the old MCStat jar in /plugins.
3. Start the server or proxy again.

This avoids classloader issues, broken reloads, and partial update corruption.

What MCStat Sends

When enabled, MCStat sends:

• Server name and version
• Online player count
• Max player count
• Uptime
• Timestamp
• TPS on Bukkit-family servers
• Player UUIDs and names
• Session start times
• Tracked playtime
• Join and leave events

Requests are signed with the server API key and installation ID.

Troubleshooting

/mcstat status says API key is invalid

Create a new server API key in the MCStat dashboard, paste it into the config, then run /mcstat reload.

Dashboard is not updating

Check:

• The server can reach https://mcstat.org
• The API key belongs to the correct server
• /mcstat status shows the API as connected
• Firewall or hosting panel is not blocking outbound HTTPS

TPS is missing on Velocity or BungeeCord

This is expected. Proxies do not expose a Minecraft game tick loop. TPS is only sent by Bukkit-family server jars.

Player events look duplicated

Install MCStat at the layer you want to measure:

• Use the proxy jar for network-wide session tracking.
• Use the Bukkit jar on backend servers for per-server analytics.

Avoid tracking the same player flow twice unless that is intentional.

Downloads

Official downloads and documentation:

• Website: https://mcstat.org/plugin
• GitHub: https://github.com/mcstatorg/MCStat-Plugin
• Latest release: https://github.com/mcstatorg/MCStat-Plugin/releases/latest

License

MIT