> **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.<\/p>\n
**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.<\/p>\n
—<\/p>\n
## Features<\/p>\n
– **Global & local bans** – issue a local ban (stays on your server) or a global ban synced to all connected servers in real time
\n– **Temporary bans** – time-limited with auto-expiry in minutes, hours, days, or weeks
\n– **IP bans** – ban by IP address to block VPN abuse and ban evasion
\n– **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
\n– **Customizable kick messages** – per-type templates (`global`, `local`, `temp`, `failsafe`) with `{reason}`, `{admin}`, `{expires}`, and `{appeal_url}` placeholders
\n– **Offline resilience** – bans issued during API outages are queued and pushed on recovery; `failsafe` mode can block all logins when the API is unreachable
\n– **Delta sync** – downloads only ban changes on a configurable interval (default 60 min)
\n– **Multiple storage backends** – SQLite (default, zero-config), MySQL\/MariaDB, PostgreSQL
\n– **Alt-account detection** – `\/altlookup` surfaces known alternate accounts via the PvPIndex API
\n– **Developer API (JitPack)** – lightweight `pvpindex-mcbans-api` module lets other plugins query ban status without a Bukkit dependency
\n– **Vault integration** – optional; swap the permission backend in one config line
\n– **Fully translatable** – swap the `language` key to load a different locale file<\/p>\n
—<\/p>\n
## Requirements<\/p>\n
| Component | Version |
\n|———–|———|
\n| Java | 21+ |
\n| Paper | 1.21+ |
\n| PvPIndex API key | Free at pvpindex.com\/apply |
\n| Vault *(optional)* | Any recent version |<\/p>\n
—<\/p>\n
## Installation<\/p>\n
1. Download `pvpindex-mcbans- “`yaml 4. Reload with `\/mcbans reload` or restart. \u2192 Full guide: docs.pvpindex.com\/mcbans\/installation<\/p>\n —<\/p>\n ## Commands<\/p>\n ### Ban commands<\/p>\n | Command | Permission | Description | ### Moderation commands<\/p>\n | Command | Permission | Description | ### Admin commands<\/p>\n | Command | Description | —<\/p>\n ## Configuration<\/p>\n “`yaml storage: language: default failsafe: false # true = block all logins when API unreachable<\/p>\n # Optional: customise the message shown to banned\/kicked players # Optional: shorthand reason keys usable in all ban commands \u2192 Full reference: docs.pvpindex.com\/mcbans\/configuration<\/p>\n —<\/p>\n ## Developer API (JitPack)<\/p>\n Add the lightweight API client to your own plugin – no Bukkit dependency required:<\/p>\n “`xml \u2192 Developer API documentation<\/p>\n —<\/p>\n ## Links<\/p>\n – **Ban registry** – mcbans.pvpindex.com —<\/p>\n ## Credits<\/p>\n 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.<\/p>\n","protected":false},"excerpt":{"rendered":" Refactored Fork of MCBans by PvPIndex<\/p>\n","protected":false},"featured_media":127030,"template":"","meta":{"_minecraft_slug":"pvpindex-mcbans","_minecraft_project_id":"8wyK7V60","_minecraft_author":"Shadow48402","_minecraft_license":"AGPL-3.0-only","_minecraft_downloads":6,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"pvpindex-mcbans.zip","_minecraft_size_bytes":50144571,"_minecraft_version_count":3,"_minecraft_updated_at":"2026-05-16T12:16:26.553312Z","_minecraft_date_created":"2026-05-08T04:05:08.688275Z","_minecraft_date_modified":"2026-05-08T08:53:00.043468Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/pvpindex-mcbans","_minecraft_icon_attachment_id":127030,"_minecraft_imported_at":"2026-06-07T11:20:32+00:00","_minecraft_import_hash":"349bf81b61b9d68ed6785042c08c105b","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,125,127,128,129],"mod_loader":[130,131,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82,83,167,163],"class_list":["post-127029","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-folia","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_loader-bukkit","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\n
\n2. Drop the JAR into `plugins\/` and start the server – `plugins\/MCBans\/config.yml` is generated automatically.
\n3. Apply for an API key and paste it into config:<\/p>\n
\npvpindex:
\n apiKey: “your-bearer-token-here”
\n“`<\/p>\n
\n5. Run `\/mcbans sync` to pull the current ban list from the network.<\/p>\n
\n|———|———–|————-|
\n| `\/ban
\n| `\/ban
\n| `\/ban
\n| `\/banip
\n| `\/unban
\n|———|———–|————-|
\n| `\/kick
\n| `\/lookup
\n| `\/banlookup
\n| `\/altlookup
\n|———|————-|
\n| `\/mcbans` | Show help |
\n| `\/mcbans reload` | Reload config and language files |
\n| `\/mcbans sync` | Force an immediate push + download cycle |
\n| `\/mcbans presets` | List all configured reason presets (`mcbans.ban.local`) |<\/p>\n
\npvpindex:
\n apiUrl: https:\/\/api.pvpindex.com
\n apiKey: “” # \u2190 paste your key here
\n syncInterval: 60 # background sync in minutes<\/p>\n
\n backend: sqlite # sqlite | mysql | postgresql<\/p>\n
\npermission: SuperPerms # SuperPerms | Vault<\/p>\n
\nkick-message:
\n global: “&cYou are globally banned.n&7Reason: {reason}n&7Appeal: {appeal_url}”
\n local: “&cYou are banned from this server.n&7Reason: {reason}”
\n temp: “&cYou are temporarily banned until {expires}.n&7Reason: {reason}”
\n failsafe: “&cUnable to verify your ban status. Try again later.”<\/p>\n
\nreason-presets:
\n hacks:
\n reason: “Hacking \/ using unauthorized modifications”
\n toxicity:
\n reason: “Toxic behaviour”
\n farming:
\n reason: “Ban\/ELO farming”
\n default-duration: “7d”
\n“`<\/p>\n
\n
\n
\n
\n
\n <\/repository>
\n<\/repositories>
\n
\n
\n
\n
\n<\/dependency>
\n“`<\/p>\n
\n– **Documentation** – docs.pvpindex.com\/mcbans
\n– **Source** – github.com\/PVP-Index\/pvpindex-mcbans
\n– **Issue tracker** – github.com\/PVP-Index\/pvpindex-mcbans\/issues
\n– **Apply for an API key** – pvpindex.com\/apply<\/p>\n