Discord Viper

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.