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:
   
   Code (YAML):

   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)

Configuration Snapshot

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

Developer API (JitPack)

Add the lightweight API client to your own plugin - no Bukkit dependency required:

→ 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.