Getting Started

Set up Madsi in a few minutes: add the bot, install the mod, and connect.

Overview

Admin

Setting up Madsi takes just a few minutes. You'll add the Discord bot, install a small Madsi mod (or plugin) on your Minecraft server, and connect the two with a token.

Step 1: Add the bot

Admin

Click Add to Discord on the homepage or go to the dashboard and select your server. The invite asks for the permissions its features need: managing roles, channels, webhooks, messages and nicknames, and viewing the audit log so ban sync can see Discord bans.

Make sure the bot's role is above any roles whose nicknames you want to sync. Discord only lets bots rename users with lower roles.

Step 2: Install the mod or plugin

Admin

Grab Madsi from the download page: choose your server software and Minecraft version and it gives you the right JAR (also available on Modrinth). Drop it into the right folder, mods/ on Fabric and NeoForge, or plugins/ on Paper/Purpur.

PlatformFolderAlso needs
Fabricmods/Fabric Loader + Fabric API
Paper / Purpurplugins/Nothing (Folia isn't supported yet)
NeoForgemods/NeoForge loader
  • Supports Minecraft 1.21.9-26.3 (Java Edition), both the 1.21.x and 26.x lines
  • Needs Java 21 for 1.21.9-1.21.11, Java 25+ for 26.1-26.3
  • Server-side only: players don't need to install anything

Step 3: Generate a token

Admin

Go to Dashboard > Servers and click Generate Token. Copy the token, it's only shown once. Only the server owner can generate or regenerate a token.

If you lose the token, you can regenerate one, but the old token stops working immediately.

Step 4: Configure the mod

Admin

There are three ways to add your token to the Minecraft server (identical on every platform):

  1. Server console: Run madsi setup <token>: no leading slash at a console prompt. Saves the token and connects immediately.
  2. In-game: Run /madsi setup <token> as a player with the madsi.admin permission. Without a permissions mod or plugin that means a level 4 operator on Fabric and NeoForge, or any operator on Paper. Also connects immediately, no restart needed.
  3. By hand: Paste the token into config/madsi.json and restart the server. This is the only route that needs a restart.
json 
{
  "token": "your-token-here"
}

Step 5: Verify

Admin

Head back to the dashboard. Your server should show as Connected within a few seconds. If not, check the Troubleshooting page.