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 NeoForge mod on the Minecraft server polls a Vör Dashboard instance and keeps whitelist.json in sync automatically.

Requires a dashboard. The actual server-side whitelist sync needs a reachable Vör Dashboard instance and the Minecraft mod installed on your Minecraft server. 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> Link your Minecraft username and whitelist yourself (works in any channel) None
/minecraft link <username> 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.

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.