PvPIndex MCBans

This is a refactored fork of the original MCBans plugin. The ban-sharing concept, command structure, and permission layout originate from the MCBans team and their contributors. This fork modernises the codebase for Java 21 / Paper 1.21+ and replaces the legacy MCBans backend with the PvPIndex REST API.

PvPIndex MCBans connects your Paper server to the mcbans.pvpindex.com global ban network. Players banned on any participating server are automatically blocked everywhere else - while you keep full control over local bans, storage backends, and permission levels.

Join the PvPIndex Discord and talk directly with our team: https://discord.gg/AGBUWhb6JQ

Features

• Global & local bans - issue a local ban (stays on your server) or a global ban (synced to all connected servers in real time)
  
• Temporary bans - time-limited bans with auto-expiry in minutes, hours, days, or weeks
  
• IP bans - ban by IP address to block VPN abuse and ban evasion
  
• Reason presets - define shorthand keys in config (#hacks, #toxicity) that expand to full reason strings; extended form supports a default-duration for temp bans; case-insensitive with tab-completion
  
• Customizable kick messages - per-type templates (global, local, temp, failsafe) with {reason}, {admin}, {expires}, and {appeal_url} placeholders
  
• Offline resilience - bans issued during API outages are queued and pushed on recovery; the failsafe option can also block all banned logins through local database when the API is unreachable
  
• Delta sync - downloads only ban changes on a configurable background interval (default 60 min), keeping the local database lightweight
  
• Multiple storage backends - SQLite (default, zero-config), MySQL/MariaDB, PostgreSQL
  
• Alt-account detection - /altlookup surfaces known alternate accounts via the PvPIndex API (premium)
  
• Developer API (JitPack) - lightweight pvpindex-mcbans-api module lets other plugins query ban status without a Bukkit dependency
  
• Vault integration - optional; swap the permission backend to Vault in one config line
  
• Fully translatable - swap the language key to load a different locale file
  

Requirements

Component	Version
Java	21+
Paper	1.21+
PvPIndex API key	Free at pvpindex.com/apply
Vault (optional)	Any recent version

Installation

1. Download pvpindex-mcbans-<version>.jar from GitHub Releases.
   
2. Drop the JAR into your server's plugins/ folder and start the server - plugins/MCBans/config.yml is generated automatically.
   
3. Apply for an API key, then set it in config:
   
   pvpindex:
   apiKey: "your-bearer-token-here"
   
   
4. Reload with /mcbans reload or restart the server.
   
5. Run /mcbans sync to pull the current ban list from the network.
   

→ Full guide: docs.pvpindex.com/mcbans/installation

Commands

Ban commands

Command	Permission	Description
/ban <player> [​reason]	mcbans.ban.local	Issue a local ban
/ban <player> g <reason> · /gban	mcbans.ban.global	Issue a global ban (synced network-wide)
/ban <player> t <n> <m|h|d|w> [​reason] · /tban	mcbans.ban.temp	Temporary ban with auto-expiry
/banip <ip> [​reason] · /ipban	mcbans.ban.ip	Ban an IP address
/unban <player|IP|UUID>	mcbans.unban	Remove any active ban

Moderation commands

Command	Permission	Description
/kick <player> [​reason]	mcbans.kick	Kick a player without banning
/lookup <player|UUID> · /lup	mcbans.lookup.player	View a player's ban history
/banlookup <id> · /blup	mcbans.lookup.ban	View a specific ban record by ID
/altlookup <player|UUID> · /alup	mcbans.lookup.alt	Show known alternate accounts

Admin commands

Command	Description
/mcbans	Show help
/mcbans reload	Reload config and language files
/mcbans sync	Force an immediate push + download cycle
/mcbans presets	List all configured reason presets (mcbans.ban.local)

→ Full reference: docs.pvpindex.com/mcbans/configuration

→ Developer API documentation

Links

• Ban registry - mcbans.pvpindex.com
  
• Documentation - docs.pvpindex.com/mcbans
  
• Source - github.com/PVP-Index/pvpindex-mcbans
  
• Issue tracker - github.com/PVP-Index/pvpindex-mcbans/issues
  
• Apply for an API key - pvpindex.com/apply
  

Credits

PvPIndex MCBans is a refactored fork of the original MCBans plugin by the MCBans team and contributors (dev.bukkit.org/projects/mcbans). The ban-sharing concept, TCP wire protocol, command set, and permission layout all originate from that project. This fork modernises the codebase for Java 21 / Paper 1.21+ and replaces the legacy MCBans backend with the PvPIndex REST API.