MCAIA

[HR]

What is MCAIA?

MCAIA is an AI administration assistant that lets server owners and admins describe requests in natural language instead of remembering complicated command syntax.

Examples:

It is especially useful for beginner server owners: you can describe the task you want completed and MCAIA can work out the command flow, inspect live server data, and continue when more information is needed.

Features

• Natural-language /ai interface
• Live server inspection for online players, player details, worlds, installed plugins, TPS, and server information
• Multi-step AI workflows using real command output instead of guessed values
• Follow-up questions with the player's next chat message treated as a private answer
• Multiple AI providers: Gemini, Groq, OpenRouter, OpenAI, Anthropic Claude, and xAI Grok
• Configurable provider priority and model fallback lists
• Administrator AI access plus optional player-scoped AI access
• Permission-aware command handling with LuckPerms/Vault integration
• Command safety guard with hard-blocked dangerous roots, configurable bans, nested execute inspection, namespaced checks, and command-chain blocking
• Configurable player request cooldown
• Per-player conversation history, reset, and automatic expiry
• Optional Geyser/Floodgate Bedrock player support
• Daily file logging and optional Discord admin webhook logging
• Admin tools: /aiadmin status, reload, clearhistory, and debug
• GitHub/Hangar update notifications and anonymous bStats metrics

Multi-Step Tasks

MCAIA is not just a chatbot. It can work through a structured loop:

When a task needs an actual seed, location, or command result, MCAIA can execute the relevant command, inspect the returned output, and use that real value for the next step.

Permissions & Safety

Administrator mode: the mcaia.use permission gives console-level AI command access for the interaction.

Player mode: when enabled, mcaia.player limits AI execution to commands the requesting player is actually allowed to run.

The command guard blocks dangerous administrative/privilege-escalating command roots and can be extended through banned-commands.yml. It also checks namespaced labels, nested execute commands, command wrappers, and command chaining.

Important: the safety system is a safeguard, not a complete sandbox or security boundary. Review the configuration, only grant access to trusted users, and keep backups.

Requirements

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

Optional integrations: LuckPerms, Vault, Geyser, Floodgate.

Installation

1. Download MCAIA and place the JAR in the server plugins/ folder.
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 AI provider API key.
6. Review models.yml and banned-commands.yml.
7. Restart the server.
8. Run /ai help.

Privacy

Prompts, relevant conversation context, live server data, and captured command output may be sent to the AI provider you configure. Debug mode can write AI request/response payloads to local logs.

Review your AI provider's privacy/data policies before enabling MCAIA. The plugin also uses bStats for anonymous metrics.