DiscordSRV setup guide
DiscordSRV setup takes 6 steps on a Paper, Purpur or Spigot server, and most of them happen in the Discord Developer Portal:
- Install the plugin from Modrinth in the plugins folder and restart once. DiscordSRV writes plugins/DiscordSRV/config.yml and complains that no bot token has been set, which is expected at this point.
- Create an application in the Discord Developer Portal. On its Installation page, turn off User Install and set Install Link to None, and on the Bot page keep Public Bot off, so nobody else can add your bot.
- Switch on 2 intents on the Bot page, SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT, then press Reset Token and copy the token.
- Invite the bot to your Discord with the bot and applications.commands scopes, and give it a role. Administrator is the short route DiscordSRV suggests; its docs also list the narrower permissions for each feature.
- Copy the channel ID: turn on Developer Mode under User Settings and Advanced, then right-click the chat channel and choose Copy ID.
- Fill in config.yml: the token between the quotes after
BotToken:and the channel ID in place of the zeros inChannels: {"global": "000000000000000000"}. Then restart the server.
The bot comes online in Discord, chat from the game appears in the channel and messages in the channel appear in the game. A new token always needs a full restart, while a change to the Channels line only needs /discord reload.
DiscordSRV config.yml settings
The DiscordSRV config.yml in plugins/DiscordSRV runs to over 300 lines, but these 6 settings are the ones you are most likely to change:
| Setting | Default | What it does |
|---|---|---|
BotToken | BOTTOKEN | The bot's token; a change needs a restart |
Channels | global and a row of zeros | Pairs of an in-game channel and a Discord channel ID |
Discord | A row of zeros | A channel that shows the console and runs commands; empty turns it off |
Discord | true | Lets the roles Owner and Developer run console commands from the chat channel with !c |
Discord | playerlist | The word that makes the bot list who is online |
Discord | A placeholder | Your Discord invite, shown with /discord in the game |
The left half of each pair in Channels is a name DiscordSRV uses in the game, not the name of your Discord channel. Player chat without a chat plugin is global, and you can send other messages elsewhere with status for start and stop, join, leave, deaths and awards for advancements. A chat plugin brings its own names: with TownyChat the main channel is usually general, which is the classic reason chat never reaches Discord.
DiscordSRV console channel
The DiscordSRV console channel streams the server console into Discord every 5 seconds and runs every message typed there as a console command, with just 4 commands blocked by default: ?, op, deop and execute. Anyone who can post in it can stop the server, ban players or turn the whitelist off.
On a public Discord we would leave DiscordConsoleChannelId empty, which turns the feature off, and use the panel's console instead. If you do want it, make the channel private to the people who already have console access. The chat channel has a smaller version of the same thing: messages starting with !c from anyone with a role named Owner or Developer run as console commands, so check who has those roles, or set DiscordChatChannelConsoleCommandEnabled to false.
How to link Minecraft and Discord accounts
To link Minecraft and Discord accounts, a player types /discord link in the game, gets a 4-digit code and sends that code to the bot in a private message on Discord. DiscordSRV then gives them the Discord role named Linked, if your Discord has one.
Linking opens a few extra options. In linking.yml, the server can refuse players who have not linked an account, and it can require them to be a member of your Discord as well, which works like a whitelist run from Discord. Our guide to the Minecraft server whitelist covers the built-in way. With synchronization.yml, DiscordSRV can also keep Discord roles and in-game groups in step, and carry bans from Discord over to the game.
DiscordSRV commands
DiscordSRV commands all start with /discord, or /discordsrv, and these 6 are the ones you will use:
| Command | What it does | For |
|---|---|---|
/discord link | Gives a code to link your Minecraft and Discord accounts | Players |
/discord linked | Shows which Discord account yours is linked to | Players |
/discord unlink | Removes the link | Players |
/discord broadcast | Posts a message in Discord | Staff |
/discord reload | Reloads the config; some changes still need a restart | Staff |
/discord debug | Uploads a debug report for support | Staff |
Use DiscordSRV's own reload, never the server's /reload or a plugin manager, which the makers say can leave the plugin broken until the next restart.
Minecraft Discord integration for Fabric, Forge and NeoForge
Minecraft Discord integration for Fabric, Forge and NeoForge needs a mod instead of DiscordSRV, because DiscordSRV 1.30.5 only runs on Bukkit-based servers such as Paper. These 3 bridges were current on Modrinth in October 2026:
- Discord Integration: Fabric and NeoForge up to 26.2 and Forge up to 1.21.11. On Fabric it needs Fabric API.
- Simple Discord Link: Fabric, Forge, NeoForge and Quilt up to 26.3, with a whitelist through Discord built in. It needs the CraterLib library mod.
- Discord MC Chat: Fabric and Quilt, with its build for 26.3 still marked beta.
Each one uses a Discord bot of your own in the same way, so the Developer Portal steps above still apply. DiscordSRV's next version, called Ascension, adds Fabric and NeoForge, but its own documentation still describes it as a future version for testing.
Why is DiscordSRV not working?
DiscordSRV not working almost always shows in the console when the server starts, and these 6 causes cover nearly every case:
- No bot token has been set in the config. BotToken still says BOTTOKEN, or the server was not restarted after you pasted the token.
- The bot token is invalid. The token was copied wrongly or reset since. Press Reset Token again, paste the new one and restart.
- Your DiscordSRV bot is lacking required intents. Switch on SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT on the Bot page.
- Chat reaches Discord, but not the game. Check that
DiscordChatChannelDiscordToMinecraftis true andDiscordChatChannelRequireLinkedAccountfalse: when the second is true, only people with a linked account can talk from Discord. - Nothing reaches Discord. A chat plugin uses another channel name than global, such as general with TownyChat, or the channel ID is wrong.
- It broke after a reload. Restart the server; the server's /reload and plugin managers leave DiscordSRV in a bad state.
Two servers on one token cause trouble as well: DiscordSRV warns that Discord treats it as API abuse, which can get the server's IP address banned from Discord. And if the token ever leaks, press Reset Token at once. The old one stops working, so put the new one in config.yml and restart.
Minecraft server status Discord bot
A Minecraft server status Discord bot tells your community whether the server is up and who is online, and some hosts build 1 into the panel, so you need no plugin for it. Astroworld Hosting's Discord bot, for example, has 6 slash commands: /status, /players, /address, /stats for the last seven days, /restart for members with Manage Server or a role you pick, and /link to connect it once with a code from the panel. It joins with no permissions, so it cannot read your channels.
A status bot and a chat bridge do different jobs and work fine side by side. Without one from your host, DiscordSRV covers the basics: typing playerlist in the chat channel lists who is online, and the status channel gets the server start and stop messages.