Skip to content
MCBridge
Docs

Reference

Plugin & config

Install

  1. Download the latest jar.
  2. Put it in your server's plugins folder and restart the server.
  3. Link it with the code from /setup: mcbridge link <code> in the console.

Requirements

  • Paper or a Paper fork (e.g. Purpur) on Minecraft 1.21.x.
  • Java 21.
  • Spigot and Folia aren't supported.
  • Role sync needs LuckPerms or Vault (with a permissions plugin).

The bot needs these Discord permissions: View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Add Reactions, Manage Webhooks, Manage Roles, Manage Channels (invite permission number 805424208).

Config reference

plugins/MCBridge/config.yml. After editing, run /mcbridge reload; no restart needed. The allow keys are checked by the plugin itself, so the bot can never do more than you allow.

config.yml keys
KeyDefaultWhat it does
bot-url"wss://bot.mcbridge.dev/v1/plugin"Where the bot is. Only change it if you host your own.
token""This server's secret. Filled in by /mcbridge link. Never share it.
update-checktrueCheck GitHub for new versions every 6 hours and tell admins.
allow.chattrueDiscord chat and /msg show in-game.
allow.whitelisttrue/whitelist and whitelist requests.
allow.moderationfalse/mod kick, ban, unban, op, deop, gamemode.
allow.rolestrueRole sync can add and remove permission groups.
allow.consolefalse/console and the console channel. Gives full control of the server.
messages.*-Every message the plugin shows, in MiniMessage or & colour codes.

Permissions

Plugin permissions
PermissionDefaultGives
mcbridge.adminop/mcbridge status, link, reload and help
mcbridge.linkeveryone/discord link (account linking)

In-game commands

In-game commands
CommandPermission (default)What it does
/mcbridge or /mcbridge statusmcbridge.admin (op)Connection status, and an update notice if a new version is out.
/mcbridge link <code>mcbridge.admin (op)Links this server using a code from /setup. Also works in the console.
/mcbridge reloadmcbridge.admin (op)Reloads config.yml and reconnects.
/mcbridge helpmcbridge.admin (op)Lists the commands.
/discord link <code> (alias /dlink)mcbridge.link (everyone)Links your account using a code from /account link.

Messages and colour codes

Every message the plugin shows is under messages in config.yml. Use classic & colour codes, MiniMessage tags, or both in the same line. Delete a line to go back to the built-in default. Write \<code> to show a literal <code>.

Colour code examples
WriteGives
&8 · &a · &7 · &fDark grey, green, grey, white
&l · &rBold, reset
&#3ddc84Any hex colour
<gray> · <#3ddc84>MiniMessage colours
<gradient:#3ddc84:#3987e5>text</gradient>A gradient
<hover:show_text:'hi'>…</hover>Text shown on hover
<click:suggest_command:'/cmd'>…</click>Click to fill in a command

Two of the defaults, as examples:

config.yml
prefix: "&8[&#3ddc84MCBridge&8] "
private-message: "&8[&9Discord&8] &7<author> &8→ &7you&8: &f<message>"

Placeholders depend on the message: discord-chat and private-message use <author> and <message>; update-available uses <current> and <latest>. The full MiniMessage format is documented at docs.advntr.dev.

Update notifications

With update-check: true (the default) the plugin checks GitHub for a new version every 6 hours. Admins see a clickable “Update available” line, and /mcbridge status shows it too. Set it to false to turn it off.