MCAIA

MCAIA — Minecraft AI Admin

Talk to your Minecraft server instead of memorizing every command.

MCAIA is a beginner-friendly AI administration assistant for Paper servers. Ask questions or describe a task in plain language, and MCAIA can inspect live server data, ask follow-up questions, execute permitted commands, read their real output, and continue multi-step workflows.

Why MCAIA?

New server owners often know what they want to do but not the exact Minecraft or plugin command needed to do it. MCAIA turns that gap into a conversation.

/ai how many players are online?
/ai what's our current TPS?
/ai show me information about Steve
/ai list the installed plugins
/ai give everyone Speed II for 5 minutes
/ai find the nearest village and teleport me there

Features

• Natural-language /ai interface
• Live server inspection for players, worlds, plugins, TPS, and server information
• Player details including health, hunger, game mode, location, OP status, UUID, and ping
• Multi-step workflows using real command output instead of guessed values
• AI follow-up questions with private player replies
• Multiple AI providers: Gemini, Groq, OpenRouter, OpenAI, Anthropic Claude, and xAI Grok
• Configurable provider priority and model fallback lists
• Permission-aware administrator mode and optional player-scoped mode
• LuckPerms and Vault permission integration
• Command guard with hard-blocked commands, configurable bans, nested execute inspection, namespaced checks, and command-chain blocking
• Configurable request cooldown
• Per-player conversation context, history, reset, and automatic expiry
• Optional Geyser/Floodgate Bedrock player support
• Daily file logging and optional Discord admin webhook logging
• /aiadmin status, reload, history cleanup, and debug controls
• GitHub/Hangar update notifications
• Anonymous bStats metrics

A closer look at multi-step tasks

MCAIA is not limited to one AI reply. It can iterate through a structured workflow:

Request → AI decision → server query/command → real result → AI decision → answer/next action

For example, when a task needs an actual seed or coordinates, MCAIA can execute the relevant command, inspect the returned output, and use the real value for the next step.

Access control and safety

MCAIA can operate in two modes:

• Administrator mode: mcaia.use provides console-level command access for the AI interaction.
• Player mode: mcaia.player can be enabled so commands are checked against the requesting player's own permissions before dispatch.

Dangerous administrative/privilege-escalating command roots are hard-blocked, and server owners can add more entries through banned-commands.yml.

The safety system is designed to reduce misuse and dangerous mistakes. It is not a complete sandbox or security boundary. Treat AI command execution as privileged automation, review the configuration, and keep backups.

Requirements

• Paper 26.2–26.3
• Java 25
• At least one supported AI provider API key

Optional: LuckPerms, Vault, Geyser, Floodgate.

Installation

1. Download MCAIA and place the JAR in plugins/.
2. Start the server once.
3. Open plugins/MCAIA/config.yml.
4. Review the Terms of Service and set tos-accepted: true.
5. Add at least one provider API key.
6. Review models.yml and banned-commands.yml.
7. Restart the server.
8. Run /ai help.

Important privacy note

Prompts, relevant conversation context, live server data, and command output may be sent to the AI provider you configure. Command output can contain server or player information. Debug logging can expose AI request/response payloads in local logs. Review your AI provider's policies before enabling MCAIA.

MCAIA also uses bStats for anonymous metrics.

Support

Discord: https://discord.gg/C4anUJdynJ GitHub: https://github.com/TIS199/MCAIA

MCAIA is licensed under GPL-3.0-only.