How to Sync Discord Roles with Minecraft Server Ranks

Why Sync Roles and Ranks?

When you sync discord roles minecraft ranks, your community gets a unified identity. A player who earns VIP in-game automatically gets the VIP role in Discord, unlocking exclusive channels, colored names, and social proof. It eliminates manual role assignment, reduces fraud, and keeps both platforms consistent.

This guide uses DiscordSRV's built-in group synchronization paired with LuckPerms, the most common permissions plugin. If you have not set up DiscordSRV yet, start with our DiscordSRV setup guide.

Prerequisites

• A working DiscordSRV installation (see our Discord bot setup guide)
• LuckPerms installed and configured with your rank groups
• The Discord bot must have the Manage Roles permission
• The bot's role in Discord must be positioned above any roles it needs to assign

Step 1, Configure DiscordSRV Group Sync

Open plugins/DiscordSRV/synchronization.yml. This is where you define the mapping between Minecraft permission groups and Discord roles.

The basic format is:

GroupRoleSynchronizationGroupsAndRolesToSync:
  "vip": "DISCORD_ROLE_ID_HERE"
  "moderator": "DISCORD_ROLE_ID_HERE"
  "admin": "DISCORD_ROLE_ID_HERE"

Replace the left side with the exact LuckPerms group name (case-sensitive) and the right side with the Discord role ID. To get a role ID, enable Developer Mode in Discord, go to Server Settings > Roles, right-click the role, and select Copy Role ID.

Sync Direction

DiscordSRV supports three sync directions:

1. Minecraft to Discord, ranks earned in-game are pushed to Discord roles. This is the most common setup.
2. Discord to Minecraft, Discord roles grant in-game permissions. Useful for Patreon or subscription-based perks.
3. Bidirectional, changes on either side propagate to the other.

Set the direction in synchronization.yml:

GroupRoleSynchronizationDirection: "minecraft to discord"

Step 2, Account Linking

For group sync to work, players must link their Minecraft and Discord accounts. DiscordSRV provides a built-in linking system. Players type /discord link in-game and receive a code. They then DM the bot with that code to complete the link.

You can also enable automatic linking if your server uses online-mode authentication:

MinecraftDiscordAccountLinkedConsoleCommands: []
MinecraftDiscordAccountLinkedRoleNameToAddUserTo: ["Linked"]

This assigns a "Linked" role in Discord to anyone who completes the linking process, giving them access to member-only channels.

Step 3, Test the Sync

After saving the config and restarting, test with a staff alt account:

1. Link the account using /discord link.
2. Assign a LuckPerms group: /lp user TestPlayer parent set vip.
3. Wait up to 60 seconds, DiscordSRV syncs on a timer, not instantly.
4. Check if the corresponding Discord role was applied.

If the role does not appear, check the server console for DiscordSRV errors. The most common issue is the bot's role being positioned below the target role in Discord's role hierarchy, Discord prevents bots from assigning roles above their own.

Handling Multiple Ranks

LuckPerms supports group inheritance. If your rank ladder is Default > VIP > MVP > Admin, a player with the Admin group inherits all lower groups. DiscordSRV can be configured to only sync the primary (highest) group, or to sync all inherited groups:

GroupRoleSynchronizationPrimaryGroupOnly: false

Setting this to false means an Admin player gets the VIP, MVP, and Admin roles in Discord simultaneously. Set it to true if you want a cleaner, single-role appearance.

Troubleshooting

• Roles not assigning: verify the bot has Manage Roles permission and its role is above the target roles in the Discord role list.
• Sync delay: DiscordSRV syncs every 60 seconds by default. You can lower GroupRoleSynchronizationCycleTime but keep it above 30 to avoid rate limits.
• Case mismatch: LuckPerms group names are case-sensitive. "VIP" and "vip" are different groups, make sure the name in synchronization.yml matches exactly what /lp group list shows.
• Unlinked players: sync only works for linked accounts. Encourage linking by gating Discord-exclusive perks behind the Linked role.

Summary

Once you sync discord roles minecraft ranks, your community runs itself. Promotions, demotions, and rank changes propagate automatically. Combined with a chat bridge and status bot, your Discord becomes a true extension of your Minecraft server, not just a side channel.

Want to see Discord integration done right? Join Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.