DiscordSRV: Discord-Bot fuer Minecraft-Server einrichten

Discord ist laengst das zweite Zuhause fuer fast jede Gaming-Community. Spieler haengen dort auch ohne Spiel ab, also macht es Sinn, den Server-Chat von dort erreichbar zu machen. DiscordSRV ist das beliebteste Plugin fuer die Verbindung von Minecraft mit Discord. Es baut eine Zwei-Wege-Chat-Bruecke, spiegelt die Konsole in einen Kanal, synchronisiert Rollen, verknuepft Accounts und sendet Alerts zu Server-Events.

Dieser Guide deckt alles ab: vom Anlegen eines Bots im Developer Portal bis zum Feintuning von Group Sync und Webhook-Nachrichten. Anleitung fuer Paper/Spigot/Purpur, gilt aber meist auch fuer andere Forks.

Was DiscordSRV kann

Die Hauptfeatures, wegen denen man es installiert:

• Chat-Bruecke: In-Game-Chat landet in einem Discord-Kanal und umgekehrt
• Konsolen-Kanal: Die Server-Konsole wird in einen privaten Kanal gespiegelt, Befehle lassen sich aus Discord ausfuehren
• Alerts: Join/Leave von Spielern, Tode, Erfolge, Server-Start/Stop
• Account Linking: Minecraft-Nick mit Discord-Account per Code verbinden
• Group Sync: LuckPerms-Gruppen mappen automatisch auf Discord-Rollen und zurueck
• Webhook-Nachrichten: In-Game-Nachrichten erscheinen in Discord mit dem Kopf-Avatar des Spielers, nicht als Bot
• Addon-API: Viele Plugins erweitern DiscordSRV (Reaktionen als Emoji, Per-Channel-Chat, Moderation)

Alternativen

Kurz zu den Konkurrenten, damit du nicht raten musst.

• DiscordIntegrator - einfacher, leichter, ohne Group Sync und Konsole. Gut, wenn nur eine Basic-Chat-Bruecke noetig ist
• EssentialsDiscord - Teil von EssentialsX, in dessen Oekosystem eingebettet. Kein Group Sync, wenig Features
• DiscordChat - minimal, nur Chat
• UltimateChat mit Discord-Addon - kostenpflichtig, schick, fuer die meisten Overkill

DiscordSRV ist der De-facto-Standard. Aktive Community, regelmaessige Updates, unterstuetzt alle aktuellen Minecraft-Versionen von 1.8 bis 1.21+. Der Rest dieses Guides richtet genau das ein.

Plugin installieren

1. Oeffne die Plugin-Seite auf SpigotMC oder GitHub Releases
2. Lade die aktuelle .jar fuer deine Minecraft-Version herunter
3. Leg die Datei in den plugins/-Ordner des Servers
4. Starte den Server neu (voller Restart, kein Reload)

Nach dem Start erscheint plugins/DiscordSRV/ mit Configs: config.yml, messages.yml, alerts.yml, synchronization.yml, linking.yml. Jetzt noch nicht anfassen, erst den Bot bauen.

Pruefe, ob das Plugin geladen ist:

/plugins

DiscordSRV sollte in gruener Farbe stehen. Rot heisst: Konsole checken. Meist eine Java- oder Minecraft-Version-Inkompatibilitaet.

Discord-Bot anlegen

Schritt 1: Anwendung erstellen

1. Oeffne das Discord Developer Portal
2. Klicke New Application oben rechts
3. Name waehlen (z.B. MyServer Bot) und AGB bestaetigen
4. Im Tab General Information kann man Icon und Beschreibung setzen. Das sehen die Spieler in Discord

Schritt 2: Bot-User erstellen

1. Links im Menue Bot waehlen
2. Add Bot -> Yes, do it!
3. Nickname und Avatar setzen (unabhaengig vom App-Namen)

Schritt 3: Token holen

Auf derselben Bot-Seite Reset Token -> Yes, do it! klicken. Du siehst etwas wie:

MTIzNDU2Nzg5MDEyMzQ1Njc4.Xy7Z_A.abcdefghijklmnopqrstuvwxyz

Sofort kopieren. Discord zeigt den Token nicht erneut, nur Reset geht. Token niemals veroeffentlichen, nicht ins Git einchecken, nicht in Screenshots zeigen. Bei Leak sofort auf derselben Seite zuruecksetzen.

Schritt 4: Privileged Intents aktivieren

Kritischer Schritt. Ohne ihn sieht der Bot keine Nachrichten.

Auf der Bot-Seite den Abschnitt Privileged Gateway Intents aktivieren:

• PRESENCE INTENT (optional, fuer Statusanzeigen)
• SERVER MEMBERS INTENT (Pflicht fuer Group Sync)
• MESSAGE CONTENT INTENT (Pflicht fuer Chat)

Save Changes klicken.

Schritt 5: Bot einladen

1. In OAuth2 -> URL Generator wechseln
2. Bei Scopes ankreuzen: bot, applications.commands
3. Bei Bot Permissions mindestens:
   • View Channels
   • Send Messages
   • Embed Links
   • Attach Files
   • Read Message History
   • Manage Messages (fuer Edit/Delete)
   • Manage Roles (fuer Group Sync)
   • Manage Webhooks (fuer schicke Avatar-Nachrichten)
   • Add Reactions
4. Unten die generierte URL kopieren
5. URL im Browser oeffnen, deinen Discord-Server waehlen, bestaetigen

Der Bot taucht in der Mitgliederliste auf, ist aber noch offline.

Channel- und Guild-IDs holen

DiscordSRV arbeitet mit numerischen IDs, nicht mit Kanalnamen. Um sie zu bekommen, Developer Mode im Discord-Client aktivieren:

1. User Settings -> Advanced -> Developer Mode: On
2. Rechtsklick auf Server (Guild) -> Copy Server ID - das ist die Guild-ID
3. Rechtsklick auf Kanal -> Copy Channel ID - das ist die Channel-ID

IDs sehen so aus: 948273194820394820. Speichere die IDs der Kanaele, die du brauchst: #minecraft-chat (globaler Chat), #console (falls Konsole spiegeln), #server-events (fuer Alerts).

DiscordSRV konfigurieren

Oeffne plugins/DiscordSRV/config.yml. Die wichtigsten Einstellungen:

BotToken

BotToken: "MTIzNDU2Nzg5MDEyMzQ1Njc4.Xy7Z_A.abcdefghijklmnopqrstuvwxyz"

Token aus dem Developer Portal einfuegen. Ohne ihn startet der Bot nicht.

Channels

Hier werden die In-Game-Kanaele von DiscordSRV auf Discord-Kanaele gemappt. global ist der Default fuer allgemeinen Chat.

Channels:
  global: "948273194820394820"
  staff: "948273194820394821"

Linker Wert (global, staff) ist der DiscordSRV-Kanalname, rechts die Discord-Channel-ID. Mehrere Kanaele erlauben, Staff-Chat von Public zu trennen.

Konsolen-Kanal

Eigener Abschnitt fuer Konsolen-Mirror:

DiscordConsoleChannelId: "948273194820394822"
DiscordConsoleChannelUsageLog: true
DiscordConsoleChannelBlacklistedCommands:
  - "?"
  - "op"
  - "deop"
  - "stop"

Der Kanal muss privat sein und nur fuer Admins zugaenglich. Jeder, der dort posten kann, kann Server-Befehle ausfuehren.

MinecraftChatToDiscordMessageFormat

Format fuer In-Game-Nachrichten in Discord, in messages.yml:

MinecraftChatToDiscordMessage:
  Content: "%message%"
  Webhook:
    Enable: true
    AvatarUrl: "https://mc-heads.net/avatar/%uuid%/128"
    Username: "%username%"

Der Webhook-Modus laesst Nachrichten wie normale Discord-Nachrichten aussehen: Kopf-Avatar des Spielers und sein Nickname, statt als Bot. Empfohlen.

DiscordChatChannelMinecraftMessage

Format fuer die Rueckrichtung von Discord nach Minecraft.

DiscordToMinecraftChatMessageFormat: "&b[Discord] &r<%username%> %message%"
DiscordToMinecraftChatMessageFormatNoPrimaryGroup: "&b[Discord] &r<%username%> %message%"

Farben per &-Codes. %username% ist der Discord-Nick, %message% der Text.

Minimale funktionierende config.yml:

BotToken: "YOUR_TOKEN_HERE"

Channels:
  global: "948273194820394820"

DiscordConsoleChannelId: "948273194820394822"
DiscordConsoleChannelUsageLog: true

DiscordChatChannelPrefixRequiredToProcessMessage: ""

MinecraftDiscordAccountLinkedConsoleCommands:
  - "lp user %player% parent add verified"

MinecraftDiscordAccountUnlinkedConsoleCommands:
  - "lp user %player% parent remove verified"

Speichern, im Spiel /discord reload ausfuehren, das Plugin zieht Aenderungen ohne Server-Restart.

Account Linking

Damit DiscordSRV weiss, welcher Discord-User zu welchem Spieler gehoert, braucht es Linking. Ohne laufen Group Sync und persoenliche Avatare nicht.

Link-Ablauf

1. Spieler tippt /discord link in Minecraft
2. Plugin gibt einen 4-stelligen Code zurueck, z.B. 4829
3. Spieler schreibt dem Bot per DM in Discord: link 4829
4. Bot bestaetigt, Link ist gespeichert

Code ist einmalig und laeuft ab (15 Minuten Default). Trennen: /discord unlink im Spiel oder unlink per DM.

Automatische Rolle beim Link

linking.yml konfiguriert Auto-Rollen:

MinecraftDiscordAccountLinkedRoleNameToAddUserTo: "Verified"
MinecraftDiscordAccountLinkedConsoleCommands:
  - "lp user %player% parent add verified"
  - "say %player% hat Discord verknuepft!"

Der Spieler bekommt die Rolle Verified in Discord und die Gruppe verified in LuckPerms direkt nach dem Link. Praktisch, um verifizierte Spieler von zufaelligen Besuchern zu trennen.

Link erzwingen

Man kann den Server hinter Discord-Linking sperren. In config.yml:

Require linked account to play:
  Enabled: true
  Subtract from online count: true
  Kick message: "Verknuepfe Discord: /discord link | Invite: discord.gg/deinserver"
  Whitelisted players bypass check: true

Nur verknuepfte Spieler kommen rein. Whitelisted koennen umgehen.

Group Sync

Eines der nuetzlichsten Features. Konfiguriert in synchronization.yml.

GroupRoleSynchronizationGroupsAndRolesToSync:
  "admin": "948273194820394830"
  "moderator": "948273194820394831"
  "vip": "948273194820394832"
  "donator": "948273194820394833"
  "member": "948273194820394834"

GroupRoleSynchronizationOneWay: false
GroupRoleSynchronizationCycleTime: 10

Links eine LuckPerms-Gruppe (oder Permission), rechts die Discord-Rollen-ID. Default ist Zwei-Wege-Sync: bekommst du Admin in LuckPerms, bekommst du @Admin in Discord und umgekehrt.

OneWay: true macht DiscordSRV nur zum Leser aus Minecraft und Schreiber nach Discord, ohne LuckPerms zurueck zu beruehren. Sicherer, falls jemand mit Discord-Rechten nicht versehentlich Serverrechte bekommen soll.

CycleTime: 10 ist das Intervall in Minuten fuer die Neuberechnung. Zusaetzlich triggert es bei Events (join, Rollenaenderung).

Rollen-Hierarchie

Der Bot kann nur Rollen vergeben, die unter seiner eigenen in der Discord-Hierarchie stehen. In den Server-Settings die Bot-Rolle ueber alle synchronisierten Rollen ziehen. Sonst bekommst du Missing Permissions in der Konsole.

Alerts

Datei alerts.yml. Erlaubt, beliebige Server-Events als Custom-Nachrichten in einen Kanal zu schicken.

Alerts:
  - Trigger: "PlayerJoinEvent"
    Async: true
    Channel: "server-events"
    Content: ":green_circle: **%player%** ist dem Server beigetreten"

  - Trigger: "PlayerDeathEvent"
    Async: true
    Channel: "server-events"
    Content: ":skull: %player% ist gestorben: `%event.deathMessage%`"

  - Trigger: "PlayerAdvancementDoneEvent"
    Async: true
    Conditions:
      - "event.advancement.display != null"
    Channel: "server-events"
    Content: ":trophy: **%player%** hat **%event.advancement.display.title%** erhalten"

Trigger sind beliebige Bukkit-Events. Conditions filtern, z.B. versteckte Erfolge ausschliessen.

Fuer Server-Events (Start, Stop, Crash) gibt es Built-ins in config.yml:

DiscordChatChannelServerStartupMessage: ":green_circle: Server gestartet"
DiscordChatChannelServerShutdownMessage: ":red_circle: Server gestoppt"

Webhook-Nachrichten fuer bessere Optik

Wenn du in messages.yml aktivierst:

MinecraftChatToDiscordMessage:
  Webhook:
    Enable: true
    AvatarUrl: "https://mc-heads.net/avatar/%uuid%/128"
    Username: "%username%"

Erscheinen In-Game-Nachrichten als eigene "User" in Discord, jeder mit eigenem Avatar, dem Minecraft-Kopf. Visuell deutlich besser als alles ueber den Bot mit einem Namen.

Wichtig: Der Bot braucht Manage Webhooks im Kanal, sonst funktioniert nichts. Discord limitiert auch Webhook-Nachrichten pro Minute. Auf kleinen Servern egal, bei 100+ Online kann es Grenzen treffen. Dann Webhook abschalten oder batchen.

Whitelist per Discord

Man kann Server-Zugang an eine Discord-Rolle binden. Z.B. die Rolle @Member soll Whitelist geben.

Per Group Sync: @Member auf die LuckPerms-Gruppe whitelisted mappen, die essentials.whitelist.bypass hat, oder per Custom-Commands in whitelist.json eintragen:

MinecraftDiscordAccountLinkedConsoleCommands:
  - "whitelist add %player%"

MinecraftDiscordAccountUnlinkedConsoleCommands:
  - "whitelist remove %player%"

Oder einen eigenen Alert auf DiscordSRVs RoleAddEvent per Addon-Plugin schreiben. Fuer die meisten Server reicht die einfache Group-Sync-Kombi.

Troubleshooting

"No such channel" beim Start

Plugin loggt Could not find Discord channel by ID.... Ursachen:

• Channel-ID falsch kopiert (Leerzeichen, Buchstaben statt Ziffern)
• Bot nicht auf dem Server eingeladen, auf dem der Kanal liegt
• Bot hat keine View-Channel-Berechtigung
• Kanal ist Kategorie oder Voice-Channel, DiscordSRV erwartet Text

Check: Discord-Kanal-Settings -> Permissions, Bot-Rolle finden, View Channel aktivieren.

"Missing Permissions" beim Rollen-Zuweisen

WARN: Tried to assign role but lacks permissions

Zwei Ursachen:

1. Bot-Rolle in Discord-Hierarchie niedriger als die zugewiesene Rolle. Fix: Bot-Rolle in Server -> Roles hochziehen
2. Bot hat kein Manage Roles. Fix: Server Settings -> Roles -> Bot-Rolle -> Manage Roles aktivieren

Nachrichten gehen nicht von Minecraft nach Discord

• Pruefe, ob global in Channels: die richtige ID hat
• Pruefe, ob der Bot online ist (/discord im Spiel zeigt Status)
• Schau in die Server-Konsole auf JDA-Fehler (DiscordSRVs Library)

Nachrichten gehen nicht von Discord nach Minecraft

Fast immer: Message Content Intent ist im Developer Portal nicht aktiviert. Discord-Policy seit 2022, ohne dieses Intent sieht der Bot keinen Inhalt. Aktivieren, Server neu starten, erneut pruefen.

Webhook-Nachrichten funktionieren nicht

• Bot hat kein Manage Webhooks im Kanal
• Discord-Limit pro Kanal (10 Webhooks) erreicht
• Proxy/CDN blockiert ausgehende Webhook-Requests vom Minecraft-Server

Bot haengt bei "Connecting..."

• Token falsch oder wurde zurueckgesetzt, neuen generieren
• Token hat Leerzeichen oder Zeilenumbruch
• Hosting blockt ausgehende Verbindungen zu gateway.discord.gg

Group Sync geht nur in eine Richtung

Pruefe GroupRoleSynchronizationOneWay. Bei true geht Sync nur MC -> Discord. Auf false setzen fuer beide Richtungen.

Auch pruefen, ob die LuckPerms-Gruppen existieren (/lp group <name> info).

Sicherheit und Best Practices

1. Konsolen-Kanal nur fuer Admins. Wer dort posten darf, kann Server-Befehle ausfuehren. Nur an Vertrauenspersonen geben
2. Token im Passwort-Manager sichern. Bei Leak sofort zuruecksetzen
3. Getrennte Kanaele nach Rolle: #minecraft-chat oeffentlich, #staff-chat privat fuer Moderation, #server-events fuer Alerts, #console fuer Admins
4. Webhook fuer Chat bei 200+ Online meiden. Discord-Ratelimits fangen an zu zicken
5. Bot-Rolle ueber Sync-Rollen. Spart Stunden an Debugging
6. Alerts sparsam. Ein Kanal mit 100 Alerts pro Minute wird von niemandem gelesen
7. DiscordSRV aktuell halten. Discord aendert die API regelmaessig, alte Versionen treiben weg

Finale Checkliste

• DiscordSRV-Plugin in plugins/, Server gestartet, Plugin gruen
• Bot im Developer Portal erstellt, Token gespeichert
• Drei Privileged Intents aktiv (SERVER_MEMBERS, MESSAGE_CONTENT, PRESENCE)
• Bot ueber OAuth2-URL mit passenden Permissions eingeladen
• Developer Mode an, Kanal-IDs kopiert
• config.yml mit BotToken, Channels, DiscordConsoleChannelId gefuellt
• synchronization.yml fuer Group Sync gesetzt (falls noetig)
• Bot-Rolle ueber allen Sync-Rollen in der Hierarchie
• Konsolen-Kanal ist privat
• Account Linking per /discord link getestet
• Nachrichten laufen in beide Richtungen

Wenn alle Haken sitzen, ist DiscordSRV produktionsreif. Danach kann man Addons nachziehen: DiscordSRV-Reactions fuer Emoji-Reaktionen im Spiel, DiscordSRV-Voice fuer Voice-Channel-Anzeige, SRVLinker fuer erweitertes Linking, und den Server in ein volles Oekosystem verwandeln.