🛡️ MCLocalAuth

Minecraft Authentication Plugin with Integrated Discord Bot

🎯 Description

MCLocalAuth is a security plugin for Minecraft servers that uses Discord as an authentication system. Protect your server by limiting access to only members of your Discord community.

Works on Spigot/Paper, BungeeCord and Velocity — the Discord bot runs on all 3 platforms with all features.

🎮 How It Works

1. Player Connects → Immediately disconnected with a unique code
2. On Discord → Type /mclogin <code> (on server or in DMs with the bot)
3. Bot Verifies → Is the player a Discord member?
4. If Yes → IP registered, reconnection authorized ✅
5. If No → Blocked ❌

📊 Usage Statistics

Spigot / Paper :

BungeeCord :

Velocity :

✨ Features

🔐 Triple Layer Security

• ✅ Discord Required: Only members of your Discord can play
• ✅ Temporary Code: Each connection generates a unique code that expires
• ✅ IP Protection: One username = One IP → Impossible to steal identities

🤖 Integrated Discord Bot

• Starts automatically with the server
• No external bot to host
• No network ports to open
• Native Discord slash commands
• Works on Spigot/Paper, BungeeCord and Velocity
• Commands available in DMs (globally registered)
• Automatic bot status verification at startup

🗄️ Flexible Storage

• YAML (default): local data.yml file
• MySQL (optional): shared database across servers
• Ideal for multi-server networks (BungeeCord/Velocity)

🔔 Auto Update Checker

• Checks Modrinth API at startup
• Console notification if a newer version is available

🎮 Geyser/Bedrock Support

• Automatic Bedrock player detection
• Adapted kick messages (no color codes)

📋 Discord Commands

Admin commands are restricted to the Discord ID set in admin.discord_id in config.yml.

⚙️ Admin Commands (in-game)

📦 Installation

Prerequisites

• Minecraft Server 1.8.9 to 26.2 (Spigot, Paper, Purpur), BungeeCord or Velocity 3.3.0+
• Java 8 minimum (Spigot/BungeeCord) · Java 17 minimum (Velocity)
• Discord Bot configured on Discord Developer Portal

Spigot / Paper / BungeeCord

1. Download MCLocalAuth-v1.4.1.jar
2. Place the file in your server's plugins/ folder
3. Start the server to generate configuration
4. Configure the Discord bot in plugins/MCLocalAuth/config.yml:

discord:
  enabled: true
  bot_token: "YOUR_DISCORD_BOT_TOKEN"
  guild_id: "YOUR_DISCORD_SERVER_ID"
  invite_link: ""

admin:
  discord_id: "YOUR_DISCORD_ID"

storage:
  type: "yaml"       # yaml or mysql
  mysql:
    host: "localhost"
    port: 3306
    database: "mclocalauth"
    username: "root"
    password: ""

1. Restart the server
2. Test with /mctest on Discord

Velocity

1. Download MCLocalAuth-Velocity-v1.4.1.jar
2. Place in your proxy's plugins/ folder
3. Configure plugins/mclocalauth/config.yml
4. Restart the proxy

🔧 Configuration

Discord Bot Setup

1. Go to Discord Developer Portal
2. Create a new application
3. Bot tab → Create a bot
4. Copy the token (never share it!)
5. Enable these Privileged Gateway Intents:
   • ✅ Server Members Intent
   • ✅ Message Content Intent (optional)
6. OAuth2 → URL Generator tab:
   • Check bot and applications.commands
   • Permissions: Administrator (or custom)
7. Invite the bot to your server with the generated URL

Get Discord Server ID

1. Enable Developer Mode in Discord:
   • Settings → Advanced → Developer Mode
2. Right-click on your server → Copy Server ID
3. Paste in guild_id in config.yml

📊 Compatibility

Java: 8+ (Spigot/BungeeCord) · 17+ (Velocity)
Note: The plugin automatically detects your Minecraft version at startup.

🐛 Report a Bug

If you encounter a problem:

1. Verify you're using the latest version
2. Check existing Issues
3. If the problem persists, open a new issue with:
   • Plugin version
   • Minecraft version
   • Server logs
   • Detailed problem description

💡 Suggest a Feature

Have an idea? Open an issue with the enhancement tag!

📜 License

This project is under proprietary license. See the LICENSE file for more details.

TL;DR:

• ✅ Free use on Minecraft servers
• ✅ View code to learn
• ❌ No modification/redistribution
• ❌ No commercial use

🙏 Credits

Developer: UNGEUR

Libraries used:

• JDA - Java Discord API
• Spigot API - Minecraft Server API
• BungeeCord API - Proxy API
• Velocity API - Proxy API
• bStats - Plugin Metrics

📞 Support

• Discord: Discord Server
• Issues: GitHub Issues