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
/votecommand 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
- Download the jar matching your platform.
- Put the jar in your server or proxy
/pluginsfolder. - Restart the server or proxy.
- Open the generated MCStat config file.
- Paste your server API key from the MCStat dashboard.
- Run
/mcstat reload. - 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
| Key | Description |
|---|---|
api-key |
Server API key generated from the MCStat dashboard. |
api-base-url |
MCStat API host. Keep as https://mcstat.org unless instructed otherwise. |
sync-interval |
Heartbeat interval in seconds. Minimum is 10. |
metrics.tps |
Sends TPS on Bukkit-family servers. Ignored by proxies. |
metrics.player-playtime |
Tracks player sessions and playtime locally. |
metrics.player-events |
Sends join and leave events when enabled. |
updates.check |
Checks GitHub Releases for newer plugin versions. |
updates.notify-admins |
Logs one warning when a newer version is available. |
updates.auto-download |
Optional. Downloads the new jar into the local updates folder. Does not replace the running jar. |
updates.check-interval-hours |
Update check interval in hours. Minimum is 1. |
Commands
| Command | Description |
|---|---|
/mcstat status |
Shows API connection, queue size, tracked players, uptime, version, and update status. |
/mcstat reload |
Reloads config, validates the API key, and restarts heartbeat scheduling. |
/mcstat link |
Shows masked API key info and dashboard link. |
/mcstat update |
Checks whether a newer plugin version is available. |
/mcstat update download |
Downloads the matching platform jar into the safe updates folder. |
/vote |
Shows the public MCStat vote link for the connected server. |
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:
- Stop the server or proxy.
- Replace the old MCStat jar in
/plugins. - 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 statusshows 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
-
umutxyp Owner
Comments