Guides

Getting started

What works immediately without touching your Minecraft server — and how to set it up.

A large part of the bot does not need your server at all. Status, charts, images, embeds and voice channels work from the public address — the same one players connect to. Only chat, whitelist and commands need a real link into the game.

1. Invite the bot via invite.mc-sync.eu and pick your Discord server.
2. Run /setup. It first asks what you want to set up, then asks exactly one question per step.
3. /server add name: Survival address: your-address.net registers your server once — /status, /embed, /voice-channel and /default-ip can all point at it by name afterwards.
4. /language sets the language the bot replies to you in.

/help shows the same overview inside Discord, sorted into the same groups as the command reference on this site.

The server list

One entry per Minecraft server — address, edition and chat sync together.

Before /server, a Minecraft server was several separate things nobody connected: an address typed into /status, /embed and every voice channel by hand, and a chat sync created with /chat-sync add that knew nothing about that address. Moving to a new domain meant finding every one of those places.

/server add name: Survival address: play.example.eu
/server settings server: Survival chat-sync: #minecraft - Survival
/server list

Both halves stay optional, and either one alone is a real case: an entry without an address is a server you cannot ping from outside; one without a chat sync is a server with no plugin or mod running. The bot works without a plugin too — then it shows exactly what a ping returns.

settings changes one field at a time; clear removes a single entry (address, chat sync or edition) without deleting the whole server. remove only takes the server off this list — an attached chat sync keeps running under its own name.

Setting up chat sync

Minecraft chat in a Discord channel and Discord messages back into the game — through the plugin, with no open port.

This needs the MC-Sync plugin on your server. It opens the connection itself, outbound: an ordinary HTTPS request that stays open. You do not have to forward a port or register an address anywhere.

1. Download the right file: mc-sync.eu/plugin. There is one per loader and version range.
2. Put it into plugins (Spigot, Paper) or mods (Fabric, Quilt, Forge, NeoForge) and restart the server once. That creates the config file.
3. In Discord, run /chat-sync add channel: #your-channel name: Survival. The bot replies with a token, visible to you alone.
4. Put the token into the plugin's config.yml and restart the server again.

# plugins/MC-Sync/config.yml
token: "your-token-from-discord"

# Optional. poll is the fallback for networks that cut
# long-lived connections — otherwise not needed.
transport:
  mode: auto   # auto | poll

What is transferred is up to you, switch by switch. They all live on /chat-sync settings:

/chat-sync settings name: #minecraft - Survival death-messages: False
/chat-sync settings name: #minecraft - Survival channel: #minecraft-new

There is one file per loader and version range. Which one you need depends on your server:

Running commands from Discord

whitelist add, say or kick from Discord — over the same connection chat sync already uses.

Once chat sync is in place, the same path can carry commands. It needs no open port and no extra password.

Two questions are answered separately, and that matters. Who may ask is settled in Discord, per role, under /server-command permission. What your server accepts is settled in config.yml. Both have to agree.

/server-command permission add role: @Moderator commands: whitelist,say,kick
/server-command permission list
/server-command run command: whitelist add Notch

On the server side, commands.mode decides what gets through at all:

# plugins/MC-Sync/config.yml
commands:
  mode: allow
  allow:
    - say
    - kick

The command is entered without the leading slash. Both sides always answer: a rejected command comes back as “rejected” rather than as silence — and, if /alerts audit-channel is set, as a line in the audit log too. Console output is not transferred — what is reported is that the command ran.

Whitelist channel

A channel where players post their Minecraft name and the bot whitelists them.

Instead of somebody on the team typing every name by hand, the bot does it: it reads the name, verifies it with Mojang and whitelists it through the plugin. A name that does not exist is never passed on.

/whitelist-channel add channel: #whitelist role: @Member
/whitelist-channel list

mode decides what happens to a valid name:

server picks which registered Minecraft server (/server add) this channel whitelists to — skip it if you only have one. Without role anyone in the channel may submit a name; up to three roles narrow that down — to everyone who has been through an application, for instance.

Embeds and voice channels

Two ways to keep the server state visible without anyone running a command.

An embed is a message the bot rewrites every five minutes. It stays where it is instead of filling the channel with repeats.

/embed add type: Status ip: play.example.eu channel: #server-info
/embed add type: Diagram ip: play.example.eu
/embed list
/embed remove embed: #server-info — status — play.example.eu

A voice channel does the same in its name — visible at the top of the list without anyone opening a channel. Status, player count and version are available.

/voice-channel add type: Status ip: play.example.eu
/voice-channel add type: Players ip: play.example.eu

For voice channels the bot needs “Manage Channels”, and for embeds it needs permission to send and edit messages in the target channel. If one is missing, it says so when you create it. Both also accept server: instead of ip: to point at a server registered with /server add.

Linking accounts

Who someone is in Discord, and who they are in Minecraft.

/link start prints a one-time code. Typing it in the Minecraft chat as !link <code> proves both sides at once: the code, because it was only ever shown to you in Discord, and the Minecraft name, because it came from inside the game.

1. Run /link start in Discord. You get a code valid for ten minutes.
2. In Minecraft, type: !link <code>
3. The bot confirms the link back in Discord.

The link is per Discord server, in both directions, and gone again with /link remove. It is what makes /role-sync possible, and what turns @Name written in the Minecraft chat into a real, ringing mention in Discord — for a single, unambiguous name, never for @everyone or @here.

Roles that reach into the game

A Discord role that runs a command the moment it is given or taken away.

/role-sync add role: @VIP on-grant: lp user {player} parent add vip on-revoke: lp user {player} parent remove vip
/role-sync list

{player} is replaced with the Minecraft name of whoever received or lost the role. Nothing is stored about a particular permission plugin — only the command itself, so this works with LuckPerms, PermissionsEx or a server's own rank plugin equally.

Alerts and audit log

Who hears about an outage, and where server commands leave a trail.

A short reconnect is not an outage — the bot only speaks up after 20 minutes of silence, and takes it back the moment the server answers again. /alerts role decides who gets pinged when that happens.

/alerts role role: @Staff
/alerts audit-channel channel: #server-log
/alerts console-channel channel: #server-errors
/alerts notifications server-start: False server-stop: False

Leaving role, audit-channel or console-channel empty turns that alert back off. /alerts show lists everything currently set.

Notifications and history

A message as soon as a server changes state — and what the bot records along the way.

/notification add watches a server and sends you a direct message as soon as it goes online or offline. That works for any reachable server, not just your own.

/notification add ip: play.example.eu
/notification settings notification: play.example.eu | Java active: False
/notification delete notification: play.example.eu | Java

Along the way, the bot records the state of every queried server every thirty seconds. /diagram and the diagram embeds are drawn from that. A server queried for the first time today therefore has no history covering a week.

Permissions and roles

Who sees which command, who may run it, and where each of those is set.

Discord assigns permissions per command, not per subcommand. That produces three cases, marked as badges on every command in the reference.

The bot itself needs: send and edit messages (embeds), manage channels (voice channels), manage webhooks (/news-channel) and read messages in the channel chat sync uses. If something is missing, it says which during setup.

When something does not work

The cases that reach support most often — and what they usually come down to.

If none of that helps, the support server is the quickest way. Mention the loader and Minecraft version, the command you ran and what the bot replied — that settles most cases in a single message.