MCSREloBot

A Paper/Spigot plugin that brings MCSR Ranked stats into your Minecraft server chat, oshbot-style. Players can check elo, personal bests, and daily session stats for any MCSR Ranked player.

Powered by the public MCSR Ranked API.

Commands

Command	Chat alias	What it shows
/elo [username]	+elo [username]	Season elo, peak, rank + division, W/L, matches, pb, average, forfeit rate
/pb [username]	+pb [username]	Season, all-time, and casual personal bests
/today [username]	+today [username]	Today's ranked W/L, net elo, match count, best completion
/mcsrelo reload	—	Reload config (admin)

If no username is given, the sender's own Minecraft name is used.

Example output:

[MCSR] eldoor Elo: 1310 (Peak 1366) • Emerald II (#1642) • W/L 146/130 (52.9%) • 308 Matches • 13:20 pb (18:58.0 avg) • 4.9% FF Rate

The +elo chat aliases can be disabled (chat-aliases-enabled: false) and the prefix changed (chat-prefix).

Requirements

• Paper, Spigot, or Purpur — Minecraft 1.20 through 26.2 (api-version: '1.20')
• Java 21+
• Outbound HTTPS access to api.mcsrranked.com

Installation

1. Drop MCSREloBot-x.y.z.jar into your server's plugins/ folder.
2. Restart the server.
3. Tweak plugins/MCSREloBot/config.yml if desired, then /mcsrelo reload.

Configuration

chat-aliases-enabled: true   # +elo / +pb / +today in chat
chat-prefix: "+"
cooldown-seconds: 5          # per-player cooldown between stat commands
cache-seconds: 60            # API response cache (API limit: 500 req / 10 min)
today-timezone: "UTC"        # what counts as "today" for /today
broadcast: true              # true = responses go to everyone, false = only the sender
messages:                    # all output templates + colors are editable
  ...

Permissions (LuckPerms)

Works with LuckPerms via normal Bukkit permissions — no extra setup beyond assigning nodes to groups. The plugin soft-depends on LuckPerms.

Node	Default	Purpose
mcsrelobot.use	everyone	Parent of elo/pb/today
mcsrelobot.elo	everyone	Use /elo and +elo
mcsrelobot.pb	everyone	Use /pb and +pb
mcsrelobot.today	everyone	Use /today and +today
mcsrelobot.bypass.cooldown	op	Skip the command cooldown
mcsrelobot.admin	op	Full admin access (includes reload + cooldown bypass)
mcsrelobot.admin.reload	op	/mcsrelo reload

LuckPerms examples:

/lp group default permission set mcsrelobot.use true
/lp group vip permission set mcsrelobot.bypass.cooldown true
/lp group mod permission set mcsrelobot.admin true

To make the commands opt-in instead of on by default:

/lp group default permission set mcsrelobot.use false
/lp group trusted permission set mcsrelobot.use true

Building

mvn package

The shaded jar lands in target/MCSREloBot-<version>.jar (Gson is bundled and relocated).

Notes

• All API calls run off the main thread; responses are delivered back on the main thread.
• Responses are cached for cache-seconds per player name and rate-limited per player, keeping the plugin far below the MCSR Ranked API limit of 500 requests / 10 minutes.
• Rank divisions (e.g. "Emerald II") are derived from elo: each tier below Netherite is split into three equal divisions, III lowest and I highest.