Discord Viper (ViperBridge)

ViperBridge is a high-performance, server-side only bidirectional gateway bridging Minecraft, Discord, and REST APIs. No client mods required - vanilla players connect normally.

What the mod does

Chat relay - Two-way chat between a Discord channel and in-game chat, plus rich embed alerts for joins, leaves, deaths (with the real death reason), advancements (real announcements only, no recipe spam), and server start/stop.

45 Discord commands - Every command works as a native slash /command and as a !prefix command. All slash replies are private (ephemeral): only the person who ran the command sees the answer.

Moderation system - Kick, ban, IP-ban, timed tempbans with automatic pardon (survives restarts), server-side mutes, numbered warnings, pardons, kick-all, and ban/whitelist lists. Mutes, warnings, and tempbans persist in viperbridge_punishments.json.

Player lookups - Online players read live; offline players read their saved player data: coordinates, slot-accurate inventory grids, cracked-vs-premium profile checks with skin renders, and last-seen times.

Per-command permissions - Each command has its own Discord roles/users/Minecraft-player allowlist, on/off switch, and Discord client visibility flag. /help only lists commands the requester may use.

Account linking - Players link Discord and Minecraft accounts with a one-time code (/link in Discord, /viperbridge link <code> in game). Links power per-player permissions and work with cracked (offline-mode) accounts.

Extras - Console forwarding to Discord in ~1000-character chunks with IPs spoiler-masked, live player-count channel, bot presence, and a bearer-token REST API (health, players, player info, remote commands).

Command list

Slash	Prefix	Default access	Description
/help	!help	Authorized	Show only the commands you may use
/players	!players	Authorized	List online players with ping
/player <name>	!player <name>	Authorized	Health, hunger, XP, gamemode, IP, inventory
/coords <name>	!coords <name>	Authorized	Dimension + XYZ, online or from saved data
/inventory <name>	!inventory <name>	Authorized	Slot-accurate grid: armor, offhand, hotbar, main
/profile <name>	!profile <name>	Authorized	Cracked/premium check, skin avatar, link status
/skin <name>	!skin <name>	Authorized	Full-body skin render
/link <mcname>	!link <mcname>	Everyone	Start linking, code delivered by DM
/unlink	!unlink	Authorized	Remove your account link
/kick <name> [reason]	!kick <name> [reason]	Authorized	Kick a player
/ban <name> [reason]	!ban <name> [reason]	Authorized	Ban a player
/ipban <name> [reason]	!ipban <name> [reason]	Authorized	IP-ban a player
/tempban <name> <dur> [reason]	!tempban <name> <dur> [reason]	Authorized	Timed ban, auto-pardon (30s/10m/2h/7d)
/mute <name> [dur]	!mute <name> [dur]	Authorized	Block chat + commands (empty = forever)
/unmute <name>	!unmute <name>	Authorized	Remove a mute
/mutes	!mutes	Authorized	Muted players with remaining time
/warn <name> [reason]	!warn <name> [reason]	Authorized	Numbered warning, player notified in game
/warnings <name>	!warnings <name>	Authorized	Show a player's warnings
/clearwarns <name>	!clearwarns <name>	Authorized	Clear a player's warnings
/pardon <name>	!pardon <name>	Authorized	Unban a player
/pardonip <ip>	!pardonip <ip>	Authorized	Unban an IP address
/kickall [reason]	!kickall [reason]	Authorized	Kick every online player
/banlist	!banlist	Authorized	Banned players with reasons
/kill <name>	!kill <name>	Authorized	Kill a player (must be online)
/say <message>	!say <message>	Authorized	Broadcast to all players
/command <command>	!cmd <command>	Authorized	Execute any Minecraft command
/stop	!stop	Authorized	Stop the server
/op <name>	!op <name>	Authorized	Grant operator status
/deop <name>	!deop <name>	Authorized	Remove operator status
/whitelist <action> [name]	!whitelist <action> [name]	Authorized	add/remove/on/off/list the whitelist
/gamemode <mode> [player]	!gamemode <mode> [player]	Authorized	Change gamemode
/give <player> <item> [count]	!give <player> <item> [count]	Authorized	Give items
/tp <player> <target>	!tp <player> <target>	Authorized	Teleport to a player or coordinates
/heal <name>	!heal <name>	Authorized	Restore health (must be online)
/feed <name>	!feed <name>	Authorized	Restore hunger (must be online)
/seen <name>	!seen <name>	Authorized	Last-online time (or online now)
/time <value>	!time <value>	Authorized	day/noon/night/midnight/ticks
/weather <type> [sec]	!weather <type> [sec]	Authorized	clear/rain/thunder
/save	!save	Authorized	Save all worlds to disk
/status	!status	Authorized	Players, uptime, memory, ticks overview
/uptime	!uptime	Authorized	Server uptime
/tps	!tps	Authorized	Tick info
/memory	!memory	Authorized	RAM usage
/seed	!seed	Authorized	World seed
/ping	!ping	Authorized	Bot latency
/effect <player> <effect> [sec] [lvl]	!effect <player> <effect> [sec] [lvl]	Authorized	Give a status effect
/clear <player> [item]	!clear <player> [item]	Authorized	Clear inventory
/difficulty <level>	!difficulty <level>	Authorized	peaceful/easy/normal/hard
/gamerule <rule> [value]	!gamerule <rule> [value]	Authorized	Set or query a gamerule
/spawnpoint <player> [x y z]	!spawnpoint <player> [x y z]	Authorized	Set spawn point
/setworldspawn [x y z]	!setworldspawn [x y z]	Authorized	Set world spawn
/defaultgamemode <mode>	!defaultgamemode <mode>	Authorized	Default gamemode
/sudo <player> <command>	!sudo <player> <command>	Authorized	Run a command as a player

In-game commands: /viperbridge reload (reload config), /viperbridge status, /viperbridge discord reconnect, /viperbridge link <code> (usable by every player, no OP needed).

Configuration

Edit world/viperbridge/viperbridge.json after first launch (reload in game with /viperbridge reload).

Field	Type	Default	Description
discordBotToken	string	""	Discord bot token from the Developer Portal. Required.
discordGuildId	string	""	Discord server ID. Enables instant slash-command registration and role features.
channels.chatRelayChannelId	string	""	Chat relay + prefix-command channel.
channels.consoleForwardChannelId	string	""	Server console output channel.
channels.liveStatusChannelId	string	""	Channel renamed with the live player count.
webApi.enabled	boolean	false	Enable the REST API.
webApi.port	number	8080	REST API port.
webApi.apiSecretToken	string	""	Bearer token for REST API auth.
forwardConsole	boolean	true	Master switch for console forwarding.
privacyMode	boolean	false	Full IP redaction, offline coords/inventory blocked, REST IPs hidden.
directRoleSync.syncEnabled	boolean	false	Sync Discord roles to MC teams.
directRoleSync.mappings	object	{}	Discord role ID to MC team mappings.
commandPrefix	string	"!"	Prefix for text commands.
enableDiscordCommands	boolean	true	Master switch for Discord commands.
allowedRoles	string[]	[]	Global Discord role IDs allowed to use commands.
allowedUsers	string[]	[]	Global Discord user IDs allowed to use commands.
botActivityText	string	"online players"	Bot status text (%count%, %max% placeholders).
linkCodeExpiryMinutes	number	10	How long link codes stay valid.
commandPermissions.<cmd>.enabled	boolean	true	Per-command on/off switch.
commandPermissions.<cmd>.roles	string[]	[]	Discord role IDs allowed for this command.
commandPermissions.<cmd>.users	string[]	[]	Discord user IDs allowed for this command.
commandPermissions.<cmd>.players	string[]	[]	Minecraft usernames allowed (matched via linked accounts).
commandPermissions.<cmd>.minPermission	string	"NONE"	Discord-side slash visibility: NONE, KICK_MEMBERS, BAN_MEMBERS, MODERATE_MEMBERS, MANAGE_SERVER, ADMINISTRATOR.
commandPermissions.<cmd>.open	boolean	false	Anyone may use the command (link is open by default).

Checks run in order per command: open, then players (linked MC name), then command roles/users, then the global fallback. Denied attempts get a private error visible only to the requester.

Note: the 1.21.x build uses numeric channel/guild IDs and an extra discordInviteLink field; everything else is identical.

Privacy mode

Set "privacyMode": true to lock the mod down: every IP in Discord output (console, player lookups) is fully redacted instead of spoiler-masked, REST API IP fields return "hidden", and coords/inventory refuse offline-player lookups (online players still work). Public chat relay and announcements are unaffected.

REST API

Auth header: Authorization: Bearer <apiSecretToken>.

Method	Endpoint	Auth	Description
GET	/api/health	Optional	Status, player count, ticks
GET	/api/players	Required	All online players with stats
GET	/api/player/{name}	Required	Single player info
POST	/api/command	Required	Run a command: {"command": "say hello"}

Installation

1. Install Fabric Loader (0.16.x+ for 1.21.x, 0.17.x+ for 26.x) and Fabric API on your server.
2. Download the JAR matching your Minecraft version (1.21.x, 26.1.x, 26.2.x, or 26.3) and drop it into the server mods folder.
3. Start the server once so world/viperbridge/viperbridge.json is created, then stop it.
4. Edit the config: set discordBotToken, the channel IDs under channels, and command permissions.
5. In the Discord Developer Portal, enable MESSAGE CONTENT INTENT and SERVER MEMBERS INTENT, then invite the bot.
6. Restart the server.