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 PvPIndex MCBans 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.

---

Features

- Fully translatable - issue a local ban (stays on your server) or a global ban synced to all connected servers in real time - Fully translatable - time-limited with auto-expiry in minutes, hours, days, or weeks - Fully translatable - ban by IP address to block VPN abuse and ban evasion - Fully translatable - 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 - Fully translatable - per-type templates (`global`, `local`, `temp`, `failsafe`) with `{reason}`, `{admin}`, `{expires}`, and `{appeal_url}` placeholders - Fully translatable - bans issued during API outages are queued and pushed on recovery; `failsafe` mode can block all logins when the API is unreachable - Fully translatable - downloads only ban changes on a configurable interval (default 60 min) - Fully translatable - SQLite (default, zero-config), MySQL/MariaDB, PostgreSQL - Fully translatable - `/altlookup` surfaces known alternate accounts via the PvPIndex API - Fully translatable - lightweight `pvpindex-mcbans-api` module lets other plugins query ban status without a Bukkit dependency - Fully translatable - optional; swap the permission backend 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 `plugins/` and start the server - `plugins/MCBans/config.yml` is generated automatically. 3. Apply for an API key and paste it into config:

```yaml pvpindex: apiKey: "your-bearer-token-here" ```

4. Reload with `/mcbans reload` or restart. 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 without banning | | `/lookup <player|UUID>` · `/lup` | `mcbans.lookup.player` | View ban history | | `/banlookup <id>` · `/blup` | `mcbans.lookup.ban` | View a 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

```yaml pvpindex: apiUrl: https://api.pvpindex.com apiKey: "" # ← paste your key here syncInterval: 60 # background sync in minutes

storage: backend: sqlite # sqlite | mysql | postgresql

language: default permission: SuperPerms # SuperPerms | Vault

failsafe: false # true = block all logins when API unreachable

Optional: customise the message shown to banned/kicked players

kick-message: global: "&cYou are globally banned.n&7Reason: {reason}n&7Appeal: {appeal_url}" local: "&cYou are banned from this server.n&7Reason: {reason}" temp: "&cYou are temporarily banned until {expires}.n&7Reason: {reason}" failsafe: "&cUnable to verify your ban status. Try again later."

Optional: shorthand reason keys usable in all ban commands

reason-presets: hacks: reason: "Hacking / using unauthorized modifications" toxicity: reason: "Toxic behaviour" farming: reason: "Ban/ELO farming" default-duration: "7d" ```

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

---

Developer API (JitPack)

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

```xml <repositories> <repository> <id>jitpack</id> <url>https://jitpack.io</url> </repository> </repositories> <dependency> <groupId>com.github.PVP-Index.pvpindex-mcbans</groupId> <artifactId>pvpindex-mcbans-api</artifactId> <version>1.1.0</version> </dependency> ```

→ Developer API documentation

---

Links

- Apply for an API key - Apply for an API key - Apply for an API key - %%MD1%% - Apply for an API key - %%MD2%% - Apply for an API key - %%MD3%% - Apply for an API key - %%MD4%%

---

Credits

PvPIndex MCBans is a refactored fork of the original MCBans plugin by the MCBans team and contributors (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.