GeoBlock
A Paper plugin that filters incoming connections by country using a local MaxMind GeoLite2 database, with bypass support for trusted IPs and UUIDs, optional VPN/proxy detection and Discord webhook notifications.
Features
- Country-based filtering in
blacklistorwhitelistmode (ISO 3166-1 alpha-2 codes). - IP and UUID bypass list with IPv4/IPv6 CIDR support.
- Permission integration through the standard Bukkit API: works with
LuckPerms when present, falls back to vanilla
/opotherwise. - Async Discord webhook for connection denials, with toggleable IP inclusion for privacy-conscious deployments.
- Hot configuration reload via
/geoblock reload.
Build
./gradlew build
The shaded jar is produced at build/libs/GeoBlock-<version>.jar with all
runtime dependencies relocated under fr.horizonsmp.geoBlock.lib.* to
avoid clashes with other plugins.
Run a development server
./gradlew runServer
Boots a Paper development server with the plugin loaded.
Requirements
- Java 25
- Paper 1.21.x (Minecraft
26.1.2API target) - A MaxMind GeoLite2 license key for automatic database updates, or a manually provided MMDB file under the plugin data folder.
Configuration
After the first run, edit the files generated under plugins/GeoBlock/:
config.yml— filtering mode, country list, GeoIP, VPN and Discord options. Each option is documented inline.messages.yml— user-facing strings (kick reasons, command output).whitelist.yml— bypass list (managed through commands).
The plugin reads config.yml, messages.yml and whitelist.yml at
startup and through /geoblock reload.
Commands
| Command | Permission | Description |
|---|---|---|
/geoblock reload |
geoblock.command.reload |
Reload all configuration files |
/geoblock bypass add ip <ip|cidr> |
geoblock.command.bypass |
Add an IP or CIDR to the bypass list |
/geoblock bypass add uuid <uuid> |
geoblock.command.bypass |
Add a player UUID to the bypass list |
/geoblock bypass remove ip <ip> |
geoblock.command.bypass |
Remove an IP/CIDR entry |
/geoblock bypass remove uuid <uuid> |
geoblock.command.bypass |
Remove a UUID entry |
/geoblock bypass list |
geoblock.command.bypass |
Show every bypass entry |
/geoblock help |
geoblock.admin |
Print the command summary |
geoblock.admin (default op) implies the two child permissions, so
operators get full access on a server without LuckPerms.
License
See LICENSE file.
