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.
5. If you would rather click than type: the dashboard does the same, with previews and pick lists instead of commands.

• Invite the botPick your Discord server, done
• Open the dashboardSign in with Discord
• Download plugin or modOne file per loader and version

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

The dashboard

Everything the slash commands can do — in the browser, with pick lists, previews and no typos.

The dashboard is the same setup as in Discord, seen from the other side. What you change here applies there immediately, and the other way round — there is no second configuration to keep in sync. What it adds is looking: reading the console live, the player count over time as a chart, a log of every change, a preview of an embed before it sits in the channel.

1. Go to mc-sync.eu/dashboard and sign in with Discord.
2. Pick the Discord server. Every server on which you hold “Manage Server” is listed — and where the bot is missing, you can invite it from there.
3. Pick a section on the left. Its address is /dashboard/<discord-server-id>/<section> and can be bookmarked.

• Open the dashboardSign in with Discord, session lasts eight hours
• MonitoringOutage alerts — yours, not a server's

The sections in the left column, grouped by the question they answer:

Each of those has its own section further down. The shortest ways there:

• Console, buttons and schedules
• Chat sync
• Embeds and voice channels
• Permissions and roles
• The activity log
• Monitoring and status page

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.

The dashboard holds the same list under “Servers”, with the same four fields as a form. There — and only there — an entry can also be published as a public status page: /s/<name>, reachable without signing in, plus an SVG badge for a README or a forum signature. Public are state, player count, version, address and the history — not the player list, not the Discord server behind it, not the whitelist.

• Server list in the dashboardPick a server, then “Servers”
• More about the status page

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, Folia) 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 configuration and restart the server again. /mcsync status in-game then tells you whether the connection is up.

# plugins/mc-sync/config.yml
api:
  token: "your-token-from-discord"

# What happens when a newer build is released:
# install (default) | notify | off
update:
  mode: install

# The live console in the dashboard. While nobody is
# watching it costs nothing — not a byte goes out.
console:
  live: true

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

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

The dashboard holds the same switches under “Chat sync”, and adds three things no slash command offers: the chat format — what a line looks like in Discord (as the player through a webhook, as a box or as a plain line), your own templates for join, leave, death and advancement, and a word filter in both directions —, the token's lifetime with a grace period and an expiry date, and the chat history, read straight out of Discord.

• Chat sync in the dashboardConnections, format, token, history
• /chat-sync in the command reference

In-game the plugin brings /mcsync: status shows whether the connection is up and what the server accepts in the way of commands, reload re-reads the configuration without a restart, and toggle turns the Discord chat off for yourself. The first two require the mcsync.admin permission; toggle is open to everyone — it is your own display.

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 — that is what took the place of RCON here.

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
    - whitelist add
    - lp user * parent add

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. Where the server returns console output it is included in the reply; many commands only answer in-game or not at all, and then it stays empty.

The dashboard does the same, and there you get the output: the console shows what the server replies, and who is online right now.

• Console, buttons and schedules
• /server-command in the command reference

Console, buttons and schedules

Run commands and watch them work — in the browser instead of a Discord channel.

The console in the dashboard takes the same path as /server-command run: the same connection, the same check on the Minecraft server, the same audit log. What it adds is the output. At the top is what the server says about itself — greeting, player count, version —, below that who is playing, then the console window with the command field inside it, and at the bottom the history of what was triggered last.

1. Open your Discord server in the dashboard and pick “Console” on the left.
2. If there is more than one: pick the Minecraft server. With only one the step disappears.
3. Type the command — without the leading slash — and send it. Arrow up brings back the previous one, and clicking a player's name writes it into the field.

• Open the consolePick a server, then “Console”

The live console shows what the Minecraft server prints, while it prints it. It hangs off one switch in the configuration:

# plugins/mc-sync/config.yml
console:
  live: true

Two things exist only here and not as a slash command:

• commands.mode and commands.allow
• Who may open the console

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.

The “Whitelist” section in the dashboard shows who is on it — with the name of whoever submitted them, and including the names somebody typed directly on the server. The other direction works from there too: add or remove a name, and with “Paste a list” a whole list of names at once, one per line. Commas, semicolons, bullets and quotes are cleared away in the process.

• Whitelist in the dashboardSearch, add, import lists
• /whitelist-channel in the command reference

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.

In the dashboard the area is called “Displays” and holds both in one place. It can do two things the command cannot. First the preview: pick type, channel and server, and below it stands how the embed will look in the channel — before posting, not after. Second, editing: a running display can be changed instead of being stopped and recreated. For a voice channel that includes its name — a template with placeholders such as {status} or {players}, so it is not stuck with an English sentence forever.

• Displays in the dashboardEmbeds and voice channels, with preview
• /embed in the command reference

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.

The “Linked accounts” section in the dashboard shows all of them at once: which Discord name belongs to which Minecraft name, since when, when they were last seen and which role-sync rules apply to them. A link can be cut there as well — useful when somebody has changed their Minecraft account.

• Linked accounts in the dashboardEvery account, searchable
• What it enables: role sync

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.

The dashboard puts a form around it, with a role picker and both fields side by side, and below them the line that will actually run on the server — with the name filled in instead of {player}. If the placeholder is missing it says so: without it the same command runs for everybody, which can be intended but rarely is.

• Role sync in the dashboardWith a preview of the finished command
• /role-sync in the command reference

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.

The dashboard holds the same five settings under “Alerts” as one form — role and channels as pick lists, the four reports as switches. If you want an alert that does not go to Discord but to an email address, a webhook or your phone, that is what monitoring is for.

• Alerts in the dashboard
• Monitoring: email, webhook, push

Monitoring and status page

Hear about an outage by email, webhook, push or Discord. And a page that shows the state to everyone.

Monitoring belongs to you, not to a Discord server. It needs neither the bot nor permissions anywhere — only that you sign in with Discord. You will find it in the dashboard at /dashboard/watch, as a tile next to the server picker. The links from the mails themselves — confirm and unsubscribe — still work without signing in.

• Set up monitoringIn the dashboard, with your Discord account

Every address entered is pinged once a minute. Nothing is reported until it has stayed silent for the grace period you set — which is what keeps a brief hiccup at the host from counting as an outage.

Reports travel four ways, several at once allowed: email, webhook (Discord, Slack, ntfy, Gotify or something of your own — https only), push into this browser and, if you are signed in, as a Discord direct message. Each way can be given a delay: it is only served if the matter still stands that much later. That turns several ways into an escalation instead of four copies of the same message.

The public status page answers the other half of the question: not “tell me”, but “see for yourself”. It is published in the dashboard under “Servers”, gets a name in the address and then lives at /s/<name> — no sign-in, open to anyone. There is an SVG badge to go with it, ready to embed in a README or a forum signature.

Along the way the bot records the state of every server it polls, every thirty seconds. That is what /diagram, the chart embeds and the “Statistics” area of the dashboard are built from — there over 24 hours, 7 or 30 days, with the peak and the share of reachable polls. A server polled for the first time today therefore has no week-long history yet.

Permissions and roles

Who sees which command, who may run it, who gets into the dashboard — 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 the “as the player” chat style) and read messages in the channel chat sync uses. If something is missing, it says which during setup.

The dashboard has a second layer of its own. Whoever may manage the Discord server has everything there anyway; under “Access rights” further roles can be unlocked, area by area. What stands there can only give, never take away.

• Access rights in the dashboardPick a server, then “Access rights”
• Who did what: the activity log

The activity log

Who changed what and when — and how to find it again.

The activity log records every change: who made it, when, to what — and what was refused. A console command that ran is in there, and so is a reissued token, a cut link, or an attempt by somebody without the permission. It can be filtered by action, period and name, and downloaded as CSV.

• The activity log in the dashboardUnder “Administration” in the left column
• Who may do what

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.

• Support server on Discord
• Command reference