DiscordSRV setup: Minecraft to Discord chat

DiscordSRV is a Paper plugin that logs in to Discord as a bot and connects your server to your community's Discord: game chat appears in a Discord channel and Discord messages appear in game, join, leave, death and advancement messages are posted automatically, a console channel can show the server log and accept commands, and players can link their Minecraft and Discord accounts so roles follow ranks. Setup takes about fifteen minutes: create a bot in the Discord developer portal, switch on two privileged intents, invite it, paste the token and channel IDs into config.yml, restart. The one part to take seriously is the console channel, because anyone who can type in it runs commands as the server console.

What DiscordSRV does, and what it is not#

DiscordSRV runs inside the Minecraft server process. It is not a separate bot you host somewhere; the bot account is just its identity on Discord. When the server is down, the bot goes offline with it. That is usually what you want - its presence shows whether the server is up - but it also means DiscordSRV cannot announce that the server crashed. For status messages that survive the server being down, see Discord webhooks for server status.

DiscordSRV is for Bukkit-family servers: Paper, Spigot, Purpur and similar. Fabric and NeoForge servers need a different mod (several community mods provide a chat bridge); a proxy-level bridge for Velocity networks is a separate project. Check what exists for your platform and version rather than forcing a Paper plugin onto a modded server.

Creating the Discord bot#

1. Open the Discord Developer Portal and create a New Application. Name it after your server; the name is what players see.
2. In the Bot section, reset and copy the token. This is the bot's password. You will see it once; if you lose it, reset it again.
3. On the same page, enable the two Privileged Gateway Intents DiscordSRV needs: Server Members Intent and Message Content Intent. Without Message Content, the bot cannot read what people type in Discord and the bridge only works one way.
4. In OAuth2, use the URL generator: scopes bot and applications.commands, and the permissions below. Open the generated URL and add the bot to your Discord server.

Grant only what you use. A bot with Administrator is a full takeover of your Discord if the token leaks, and the token sits in a plain text file on a game server.

Installing the plugin and the first config#

Put the DiscordSRV jar in plugins/, start the server once to generate plugins/DiscordSRV/, then stop it and edit config.yml. The keys that matter for a first setup:

BotToken: "paste-the-bot-token-here"Channels: {"global": "112233445566778899"}DiscordConsoleChannelId: "998877665544332211"DiscordGameStatus: ["Minecraft"]Experiment_WebhookChatMessageDelivery: true

What each of those does:

• `BotToken` - the token from step 2.
• `Channels` - maps in-game chat channels to Discord channel IDs. global is the main game chat. Enable Developer Mode in Discord's settings, then right-click a channel and Copy Channel ID. Plugins with their own chat channels (via a chat plugin hook) can map more entries here.
• `DiscordConsoleChannelId` - the console channel, covered below. Leave the placeholder of zeros if you do not want one.
• `Experiment_WebhookChatMessageDelivery` - posts game chat through a webhook so each message shows the player's name and skin head instead of everything coming from the bot. Looks far better, needs Manage Webhooks.

The real file is long and commented, and key names occasionally change between versions. Change what you need and leave the rest. After a restart, the console should show DiscordSRV connecting and the bot should appear online in Discord.

Message formats live in messages.yml: the format of Minecraft chat in Discord, Discord chat in Minecraft, join and leave messages, death messages, advancements, server start and stop. Defaults are sensible. The most common change is making Discord-to-game messages shorter so they do not wrap in the in-game chat box.

Chat bridge: what crosses and what should not#

By default everything said in global chat is posted to Discord, and everything posted in the linked Discord channel appears in game. A few things to decide deliberately:

• Mentions. Players typing @everyone in game should not ping your whole Discord. DiscordSRV strips or blocks mass mentions by default; check that it still does after you change formats.
• Muted players. If a player is muted in game by a moderation plugin, their messages should not reach Discord either. DiscordSRV respects the chat event being cancelled, which most mute plugins do; test it.
• Private messages and staff chat must not be bridged to a public channel. They are not by default, because they are not global chat - but a chat plugin hook can map them, so check Channels if you add one.
• Discord-only users. People who are in your Discord but not on the server can now talk to players in game. That is often the point; it is also a moderation surface. Your Discord moderation now applies to your game chat.
• Rate. A busy server's chat posted to Discord one message at a time can hit Discord's rate limits. DiscordSRV queues and retries, but on very busy servers, consider bridging only joins, deaths and announcements to a public channel and keeping full chat in a separate one. Rate limits and 429s are explained in the webhooks post.

The console channel, done safely#

A console channel posts the server log to a Discord channel and runs anything typed there as a console command. It is very convenient for staff on phones. It is also the most dangerous feature in the plugin.

If you set one up:

1. Lock the channel down. A private channel visible only to a role that only owners hold. Check the channel's permission overrides, not just the role's - Discord permissions can be granted per channel.
2. Use the command blacklist. DiscordSRV has settings to block commands from the console channel, or to turn the list into a whitelist so only listed commands run. A whitelist of a few safe commands (list, tps, say, kick) is much safer than a blacklist of dangerous ones.
3. Remember the log contains secrets. Players' IP addresses appear in join lines, plugins sometimes log tokens and passwords. A console channel copies all of it into Discord, where it is kept forever and searchable.
4. Consider not having one. If your staff already have panel access, the panel console does the same job with per-user permissions and an activity log. On RE:NODE, subusers can be given console access without file or billing access, and the panel records what each did - a more accountable way to give staff a console than a shared Discord channel. Subusers and least privilege covers how to scope that access.

Account linking#

Linking connects a Minecraft account (UUID) to a Discord account. It enables role sync, nickname sync, and requiring a linked account to play.

The default flow:

1. The player types /discord link in game.
2. DiscordSRV shows a four-digit code.
3. The player sends that code to the bot in a direct message.
4. The accounts are linked. /discord linked in game shows the link.

Links are stored by DiscordSRV, in its own files or a database if configured. Admins can link and unlink accounts by command; /discord with no arguments lists the subcommands available to you.

Requiring a linked account to join

linking.yml contains an option to refuse players who have not linked, kicking them with a message containing their code. Combined with Discord's own verification (phone or email-verified accounts, a member screening step), it turns your Discord into a gate for your server: you must be in the Discord, and pass its checks, to play. Settings beside it let you require membership of the Discord server and specific roles.

It is a reasonable whitelist replacement for a community that lives on Discord, and a barrier for anyone else. It also means that if the bot cannot reach Discord, nobody new can link and join - so make sure staff and the existing whitelist still work if Discord has an outage.

Role and group sync#

With Vault and a permissions plugin (LuckPerms) installed, DiscordSRV can synchronise permission groups and Discord roles for linked players. The mapping lives in synchronization.yml:

GroupRoleSynchronizationGroupsAndRolesToSync:  "vip": "223344556677889900"  "moderator": "334455667788990011"GroupRoleSynchronizationMinecraftIsAuthoritative: true

The group names on the left are LuckPerms groups; the numbers are Discord role IDs (copy them the same way as channel IDs). The direction setting decides which side wins when they disagree:

• Minecraft authoritative - buy VIP in game, get the VIP role in Discord. The usual choice when ranks come from a store or progression.
• Discord authoritative - give someone the Moderator role in Discord, and they get the moderator group in game. Convenient, and risky: anyone who can assign Discord roles can now grant in-game permissions.

Sync only cosmetic or community roles in the Discord-to-game direction. Never sync a group with real power - moderation, admin, * - from Discord to the game. A compromised Discord moderator account then becomes a compromised server. Two independent systems of trust are safer than one chained to the other. LuckPerms covers building those groups in the first place.

The bot's own highest role must sit above every role it manages in Discord's role list, or role changes fail silently.

Performance and failure modes#

DiscordSRV does its Discord work off the main thread, so a well-configured instance does not affect TPS. Things that can still go wrong:

The bot does not come online. Wrong or revoked token, or the privileged intents are not enabled. The console error at startup says which.

Messages flow game to Discord but not back. Message Content Intent is off, or the bot cannot see the channel. Check both.

Players appear as the bot's name instead of their own. Webhook delivery is off, or the bot lacks Manage Webhooks in that channel.

Role sync does nothing. The bot's role is below the roles it manages, the player is not linked, or Vault cannot see the permissions plugin. /discord debug uploads a diagnostic report that shows all of these; it redacts the token, but read it before sharing it anyway.

The token leaked. Reset it in the developer portal immediately - the old one stops working - and update config.yml. Then check your Discord's audit log for anything the bot did that you did not. Treat it as described in environment variables and secrets: a token is a password, and config files get shared in support chats more often than anyone admits.

The bot runs inside the game server, so it needs no hosting of its own. If you outgrow it - custom commands, tickets, moderation tools - a standalone bot is a separate program; hosting a Discord bot 24/7 covers that path.

FAQ#

Do I need to host the DiscordSRV bot somewhere?

No. It runs inside the Minecraft server, so it is online whenever the server is. You only create the bot account in the Discord developer portal to get a token.

Why can't the bot read messages from Discord?

The Message Content Intent is not enabled in the developer portal, or the bot lacks View Channels or Read Message History in that channel. Enable the intent, check channel permissions, and restart the server.

Can DiscordSRV work across a proxy network?

Each backend can run its own DiscordSRV with the same bot token and channels, which bridges every server's chat into one channel. Make sure only one of them runs the console channel, or commands will run on the wrong server.

Is the console channel safe?

Only if access to it is restricted as tightly as panel access. Everyone who can post there can run any console command. A command whitelist reduces the damage; not having one at all is safest.

Can I require players to link Discord before joining?

Yes, through the linked-account requirement in linking.yml. Unlinked players are kicked with their linking code, which they send to the bot. Keep a way in for staff if Discord or the bot is down.