Reference
Troubleshooting & FAQ
The bot isn't in the member list
It was added without the bot scope, so only its commands were installed. Add it again with the invite link, which includes the bot and applications.commands scopes.
Minecraft chat shows as the bot
Player names and skin heads need Manage Webhooks in the chat bridge channel. Give the bot that permission, or re-invite it with the current invite link.
The link code expired or didn't work
Codes work once and expire after 10 minutes. Run /setup again for a new server code, or /account link again for an account code.
Commands aren't showing
- Staff commands are hidden from members who don't have Manage Server. That's on purpose.
- An admin may have changed who can use them in Server Settings → Integrations → MCBridge.
- If no MCBridge commands show at all, add the bot again with the invite link (it needs the
applications.commandsscope).
The console channel is empty
The console is off by default. Set allow.console: true in plugins/MCBridge/config.yml and run /mcbridge reload. See Console channel.
Role sync isn't working
- Install LuckPerms, or Vault with a permissions plugin.
- Check
allow.rolesistruein the plugin config. - Move MCBridge's role above the roles it manages, in Server Settings → Roles.
- Only players who linked their account with
/account linkare synced.
FAQ
- Do I need to host anything?
- No. We host the bot. You only install the plugin on your Minecraft server. The plugin connects out to MCBridge over a secure WebSocket, so you don't need to open ports, set up port forwarding or have a static IP.
- Which servers does it work on?
- Paper or a Paper fork like Purpur, on Minecraft 1.21.x with Java 21. Spigot and Folia aren't supported. A Fabric version is on the roadmap.
- How is this different from a status bot?
- A status bot can only ping your server from the outside, so all it sees is online or offline and a player count. MCBridge runs inside the server, so it sees real TPS, MSPT and memory, knows a crash from a restart, and can find the chunks causing lag.
- How does it tell a crash from a restart?
- The plugin sends a heartbeat every few seconds and a stop message when the server shuts down cleanly. If the heartbeats stop without a stop message, that's a crash. MCBridge waits 30 seconds first, so a quick reconnect doesn't cause a false alert.
- Is the remote console safe?
- It's off by default. You have to turn it on in the plugin's config, only Discord members with the Administrator permission can use it, and every command is written to the audit log (/audit).
- Can I connect more than one server?
- Yes. Run /setup once for each Minecraft server. /servers lists everything linked to your Discord.
- What data do you store?
- Only what the features need: your server's name and settings, the channels and roles you pick, stats samples for the graphs (kept for 8 days), player names and playtime counters, linked accounts and the audit log. Chat messages are passed through, not stored. The privacy policy has the full list.
- Is it free?
- Yes. MCBridge is free to use, and the code is open source under AGPL-3.0, so you can also read it, change it or run it yourself.
Still stuck?
Ask in the MCBridge Discord. Running /mcbridge in-game shows whether the plugin is connected.