?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacksServers
Settings
PvPIndex MCBans

PvPIndex MCBans

Refactored Fork of MCBans by PvPIndex

5
1
5
1

Compatibility

Minecraft: Java Edition

26.1.x
1.21.x

Platforms

Links

Report issues View source Visit wiki Join Discord server

Creators

Details

Published 3 days ago

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.

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 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; failsafe mode can block all logins when the API is unreachable
  • Delta sync - downloads only ban changes on a configurable interval (default 60 min)
  • Multiple storage backends - SQLite (default, zero-config), MySQL/MariaDB, PostgreSQL
  • Alt-account detection - /altlookup surfaces known alternate accounts via the PvPIndex API
  • 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 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:
pvpindex:
  apiKey: "your-bearer-token-here"
  1. Reload with /mcbans reload or restart.
  2. 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

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:

<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

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.