# How to Set Up DiscordSRV on Your Minecraft Server (/docs/minecraft/setup-discordsrv)
import { Step, Steps } from 'fumadocs-ui/components/steps';
**DiscordSRV** is the most-installed plugin for connecting Minecraft and Discord. It bridges in-game chat to a Discord channel, mirrors join/leave/death messages, optionally streams console output to a private staff channel, and supports account linking so Discord roles can sync to in-game permissions.
What DiscordSRV Does [#what-discordsrv-does]
| Feature | Default state |
| ----------------------------------------- | ----------------------------- |
| Chat sync (Minecraft ↔ Discord) | Enabled |
| Join / leave / death announcements | Enabled |
| Player list in Discord (slash command) | Enabled |
| Console mirroring to a Discord channel | Optional |
| Account linking (Discord ↔ Minecraft) | Optional |
| Discord role → Minecraft group sync | Optional (requires LuckPerms) |
| Webhook avatars (player faces in Discord) | Optional |
Prerequisites [#prerequisites]
* A Discord server you have admin access to
* A Discord bot you create (this guide walks through it)
* Bukkit / Spigot / Paper Minecraft server
Step 1: Create the Discord Bot [#step-1-create-the-discord-bot]
Open the Discord Developer Portal [#open-the-discord-developer-portal]
Go to [discord.com/developers/applications](https://discord.com/developers/applications) and click **New Application**. Name it (e.g., "MyServer Bridge").
Add a bot user [#add-a-bot-user]
In the left sidebar, click **Bot**. Click **Add Bot** → **Yes, do it!**.
Disable **Public Bot** (only you should be able to invite it).
Enable required intents [#enable-required-intents]
Still on the Bot page, scroll down to **Privileged Gateway Intents** and enable:
* ✅ **Server Members Intent**
* ✅ **Message Content Intent**
Click **Save Changes**.
> **Without these intents, DiscordSRV won't see chat messages or member updates.** This is the #1 setup mistake.
Copy the bot token [#copy-the-bot-token]
Click **Reset Token** → **Yes, do it!** → **Copy**. Save this token somewhere private.
> **Critical:** Treat the bot token like a password. Anyone with it can control your bot. Never paste it in a public chat or commit it to git.
Step 2: Invite the Bot to Your Discord [#step-2-invite-the-bot-to-your-discord]
Open the OAuth2 URL Generator [#open-the-oauth2-url-generator]
In the left sidebar, click **OAuth2** → **URL Generator**.
Select scopes [#select-scopes]
Check:
* ✅ **bot**
Select bot permissions [#select-bot-permissions]
At minimum:
* ✅ **Read Messages / View Channels**
* ✅ **Send Messages**
* ✅ **Manage Messages** (for chat editing/deletion)
* ✅ **Embed Links**
* ✅ **Read Message History**
* ✅ **Use External Emojis**
* ✅ **Add Reactions**
For role sync also add:
* ✅ **Manage Roles**
Open the generated URL [#open-the-generated-url]
Copy the URL at the bottom and open it in your browser. Select your Discord server and click **Authorize**. The bot is now in your Discord (offline until DiscordSRV starts).
Step 3: Get the Channel ID [#step-3-get-the-channel-id]
Enable Developer Mode in Discord [#enable-developer-mode-in-discord]
In Discord (your client, not the dev portal): **User Settings → Advanced → Developer Mode → ON**.
Right-click your target channel [#right-click-your-target-channel]
Right-click the chat channel where you want Minecraft messages to appear (e.g., `#minecraft-chat`) → **Copy Channel ID**.
Step 4: Install DiscordSRV [#step-4-install-discordsrv]
Download DiscordSRV [#download-discordsrv]
Get the latest build from [SpigotMC](https://www.spigotmc.org/resources/discordsrv.18494/) or [Modrinth](https://modrinth.com/plugin/discordsrv).
Stop the server [#stop-the-server]
In the [XGamingServer Panel](https://panel.xgamingserver.com), open **Console** and stop your server.
Upload to plugins/ [#upload-to-plugins]
Click **Files** in the sidebar. Upload `DiscordSRV-Build.jar` to `plugins/`.
Start once to generate config [#start-once-to-generate-config]
Start the server. DiscordSRV creates `plugins/DiscordSRV/config.yml`. It will warn that the bot token is missing — that's expected. Stop the server again.
Step 5: Configure DiscordSRV [#step-5-configure-discordsrv]
Edit config.yml [#edit-configyml]
Open `plugins/DiscordSRV/config.yml` in **Files**.
Set the bot token [#set-the-bot-token]
Find:
```yaml
BotToken: "your-bot-token-here"
```
Replace with the token you copied in Step 1.
Set the chat channel ID [#set-the-chat-channel-id]
Find the `Channels` section:
```yaml
Channels:
global: "1234567890123456789"
```
Replace with the channel ID from Step 3.
(Optional) Set up the console channel [#optional-set-up-the-console-channel]
For staff-only console mirroring, find:
```yaml
DiscordConsoleChannelId: "0987654321098765432"
```
Set it to a **private** channel ID — never make this public, as console output may contain sensitive information.
Save and start the server [#save-and-start-the-server]
Click **Save Content**. Start the server. DiscordSRV connects to Discord and the bot status changes to **Online**.
Test it [#test-it]
Send a message in the configured Discord channel — it should appear in Minecraft chat. Type something in Minecraft chat — it should appear in Discord.
Common Configuration Tweaks [#common-configuration-tweaks]
Use Webhooks for Player Avatars [#use-webhooks-for-player-avatars]
In `config.yml`:
```yaml
Experiment_WebhookChatMessageDelivery: true
Experiment_WebhookChatMessageUsernameFormat: "%displayname%"
Experiment_WebhookChatMessageAvatarUrl: "https://crafatar.com/avatars/%uuid%?size=64&overlay"
```
Now Minecraft messages appear as the player's skin avatar in Discord, not the bot.
Customize Join / Leave Messages [#customize-join--leave-messages]
In `messages.yml`:
```yaml
MinecraftPlayerJoinMessage:
Embed:
Color: "00ff00"
Author:
Name: "%displayname% joined"
ImageUrl: "https://crafatar.com/avatars/%uuid%"
```
Disable Death Messages [#disable-death-messages]
```yaml
MinecraftPlayerDeathMessage:
Enabled: false
```
Account Linking [#account-linking]
Players run `/discord link` in Minecraft, get a code, and message it to the bot in Discord. Once linked, you can sync Discord roles to in-game groups (requires LuckPerms).
Discord → Minecraft Role Sync [#discord--minecraft-role-sync]
In `synchronization.yml`:
```yaml
GroupRoleSynchronizationGroupsAndRolesToSync:
"vip": "111111111111111111" # in-game group: discord role ID
"donator": "222222222222222222"
```
Players with the Discord role automatically get the Minecraft group on join.
Useful In-Game Commands [#useful-in-game-commands]
| Command | Description |
| ------------------------------ | --------------------- |
| `/discord` | DiscordSRV info |
| `/discord link` | Get a linking code |
| `/discord broadcast ` | Send to chat channel |
| `/discord reload` | Reload config |
| `/discord debug` | Generate debug report |
Slash Commands in Discord [#slash-commands-in-discord]
DiscordSRV registers Discord slash commands automatically:
| Command | Description |
| --------- | -------------------------------------- |
| `/list` | Show online players |
| `/link` | Link your Discord account to Minecraft |
| `/linked` | View your linked account |
Common Issues [#common-issues]
| Problem | Fix |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| Bot stays offline | Wrong bot token, or intents not enabled — check Step 1 |
| Discord chat not appearing in Minecraft | Wrong channel ID, or Message Content Intent not enabled |
| Minecraft chat not appearing in Discord | Bot lacks Send Messages permission in that channel |
| `Channel ID isn't a valid number` | Channel ID was pasted with quotes or whitespace — clean it up |
| `Error: 401 Unauthorized` | Token is invalid — generate a new one in the dev portal |
| `Channel not found` | Bot isn't in the server, or wrong channel ID |
| Account linking doesn't work | Players need to DM the bot — they can't `/discord link` from a server channel |
| Webhooks don't show avatars | Enable webhook experiment in config |
Common Mistakes [#common-mistakes]
| Mistake | Fix |
| -------------------------------------------- | ----------------------------------------------------------------- |
| Forgetting to enable Message Content Intent | Enable in Discord Developer Portal → Bot → Privileged Intents |
| Using a public channel for console mirroring | Console output can contain sensitive info — use a private channel |
| Sharing the bot token publicly | Reset it immediately in the Dev Portal |
| Bot not in the Discord server | Re-run the OAuth2 URL invite |
| Putting quotes around the channel ID in YAML | DiscordSRV expects them — keep the quotes |
| Editing config while server is running | Stop server first, then edit |
| Turning on too many features at once | Start minimal — chat sync only — then add features as needed |
Related Guides [#related-guides]
* [Plugin Setup](/docs/minecraft/plugin-setup)
* [Setup LuckPerms](/docs/minecraft/setup-luckperms)
* [Setup EssentialsX](/docs/minecraft/setup-essentialsx)
* [Find / Fix YAML Errors](/docs/minecraft/find-fix-yaml-errors)