New Feature

Minecraft Cog

The Minecraft cog links Discord members to a Minecraft (Java Edition) username and computes who should be allowed on your Minecraft server, based on roles and per-user overrides. A companion server mod, Vör Whitelist Sync (NeoForge and Forge), polls a Vör Dashboard instance and keeps whitelist.json in sync automatically.

Requires a dashboard and the mod. The actual server-side whitelist sync needs a reachable Vör Dashboard instance and the Vör Whitelist Sync mod installed on your Minecraft server. Download the jar for your loader and Minecraft version from its Releases page; the source is in the vor-whitelist-sync repository. Without one, the Discord-side commands below still work, but nothing will sync to your Minecraft server. See the cross-host setup guide for installing the mod and connecting it to your dashboard.

Features

  • Self-service linking: Members link their own Minecraft username with a single command.
  • Role-based allowlisting: Decide who’s allowed based on Allowed Roles and Blacklisted Roles.
  • Per-user overrides: Whitelist or blacklist individual users regardless of their roles.
  • Automatic recompute: The allowlist updates immediately when roles or lists change, plus a 10-minute safety-net refresh to catch drift.
  • Healthcheck: One command surfaces stale roles, orphaned entries, invalid usernames, duplicate links, and dashboard sync problems.
  • CSV export: Export every allowed Discord user and their linked Minecraft username.

How allow status is decided

Vör checks the following, in order, and stops at the first match:

  1. Whitelisted User — always allowed.
  2. Blacklisted User — never allowed.
  3. Blacklisted Role — not allowed.
  4. Allowed Role — allowed.
  5. Default — denied (no Allowed Role, not individually whitelisted).

Whitelisted/Blacklisted Users are managed individually (via the whitelist/blacklist subcommands below) rather than through the standard config UI, since a community whitelist can easily exceed Discord’s 25-entry select-menu limit for Roles/Members config types.

Commands

Command Description Permissions
/mc <username or UUID> Confirm your Minecraft account and whitelist yourself (works in any channel) None
/minecraft link <username or UUID> Same as /mc None
/minecraft unlink Remove your linked username None
/minecraft status Check your own linked username and allowed status None
/minecraft setup Generate or rotate this server’s dashboard API key Config Manager / Administrator
/minecraft config Configure Allowed Roles, Blacklisted Roles, Config Manager Roles Config Manager / Administrator
/minecraft healthcheck Check role mapping, lists, linked handles, and dashboard sync for issues Config Manager / Administrator
/minecraft whitelist add\|remove\|list Manage Whitelisted Users (always allowed) Config Manager / Administrator
/minecraft blacklist add\|remove\|list Manage Blacklisted Users (never allowed) Config Manager / Administrator
/minecraft export Export a CSV of allowed Discord users and their Minecraft usernames Config Manager / Administrator
/minecraft help Show an in-Discord summary of the commands above None

Usernames must match Java Edition’s format (3-16 letters, digits, or underscores) or the link is rejected. Vör looks the account up with Mojang and shows its name, UUID and skin so you can confirm it’s yours before linking. If your name isn’t found (or you want to be exact), use your account UUID instead, e.g. from NameMC.

Configuration

Configure the cog with /minecraft config (or /config cog Minecraft):

  • Enabled — Turn Minecraft whitelist sync on or off for this server. Disabling clears the computed allowlist outright, so the dashboard has nothing left to serve; re-enabling recomputes it immediately.
  • Allowed Roles — Roles whose members are allowed on the Minecraft server (up to 25).
  • Blacklisted Roles — Roles never allowed, regardless of Allowed Roles (up to 25).
  • Config Manager Roles — Roles that can run /minecraft setup, /minecraft config, and manage the whitelist/blacklist, in addition to Administrators (up to 25).

Connecting a Minecraft server

Run /minecraft setup in the server you want to sync. Vör replies (ephemerally) with:

  • A one-time API key — the dashboard only stores a hash of it, so save it now. Re-running /minecraft setup rotates the key and invalidates the old one.
  • The exact endpoint (GET /api/mc/{guildId}/whitelist) the mod polls, with the X-API-Key header it expects.
  • The last time the dashboard successfully polled this guild, so you can confirm the mod is actually connecting.

Full instructions for installing and configuring the mod on the Minecraft server itself — including running the bot and Minecraft server on different machines — are in the cross-host setup guide.

Best Practices

  1. Run /minecraft healthcheck after any role changes to catch stale roles, unlinked-but-allowed members, or a sync that’s stopped polling.
  2. Keep Blacklisted Roles reserved for punishment roles (e.g. Muted) — they override Allowed Roles, so overlapping the two silently disables the Allowed entry.
  3. Set Config Manager Roles rather than relying solely on Administrator, especially on larger servers with dedicated Minecraft moderators.
  4. Use /minecraft export for operator visibility into who’s allowed but hasn’t linked a username yet.
  5. If a member changes their Minecraft username, they should run /minecraft unlink then /mc <newname> — the mod picks up the change on its next poll.