Wiki | MCAIA | Hangar

Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

AI-powered Minecraft server administration plugin for PaperMC. Use natural language to inspect live server data, manage

MCAIA Wiki

AI-powered administration for Paper servers.

Ask what you want to accomplish, and MCAIA can inspect supported live server data, plan a structured response, execute allowed commands, consume command output, and continue multi-step tasks.

What is MCAIA?

MCAIA is a Paper server plugin that connects Minecraft administration with AI.

Instead of requiring a server owner to remember every command and every argument, MCAIA lets them describe the desired outcome in natural language.

For example:

/ai how many players are online?

or:

/ai show me the server TPS

For more advanced workflows, MCAIA can use a structured loop:

Player request
      ↓
AI understands the goal
      ↓
Query live server state
      ↓
Execute an allowed action
      ↓
Capture the result
      ↓
Return the result to the AI
      ↓
Continue or answer

This makes MCAIA more than a simple chat interface. The AI can work with current server state instead of relying only on its training data.

✨ Features

💬 Natural-language administration

Use /ai to ask questions or request supported server actions using normal language.

Examples:

/ai how many players are online?

/ai show me the current TPS

/ai list the worlds on this server

/ai tell me information about Steve

🔎 Live server information

MCAIA provides structured server queries for information such as:

Query	Information
`player_list`	Online player names and player count
`player_info:<name>`	UUID, gamemode, health, food, world, coordinates, OP state and ping
`world_list`	Worlds, environments and player counts
`plugin_list`	Loaded plugin names, versions and enabled state
`tps`	1m / 5m / 15m TPS and a basic health indicator
`server_info`	Server version, Minecraft version, player counts, MOTD and online-mode state

The AI can request these through its structured server-query system when it needs current information.

🔁 Multi-step AI workflows

A simple chatbot normally looks like:

Question → Answer

MCAIA can go further:

Question
   ↓
server_query
   ↓
real server result
   ↓
execute allowed command
   ↓
captured command output
   ↓
AI evaluates the result
   ↓
another step or final answer

MCAIA limits the number of internal iterations with:

ai:
  max-iterations: 8

This prevents an AI workflow from continuing forever.

Command output capture is also bounded. MCAIA can feed up to approximately 8,000 characters of captured command feedback into the next AI step.

🧠 Supported AI providers

MCAIA supports:

Google Gemini
Groq
OpenRouter
OpenAI
Anthropic Claude
xAI Grok

Configure at least one provider in:

plugins/MCAIA/config.yml

Example:

ai:
  providers:
    gemini:
      api-key: "YOUR_GEMINI_API_KEY"

Multiple providers can be configured at the same time.

🔄 Provider & model fallback

MCAIA separates:

Provider priority
Model priority within each provider

These are configured in:

plugins/MCAIA/models.yml

Example:

provider-order:
  - anthropic
  - openai
  - openrouter

anthropic:
  models:
    - claude-sonnet-4-5

openai:
  models:
    - gpt-4o-mini
    - gpt-4.1-mini

openrouter:
  models:
    - deepseek/deepseek-r1:free
    - openai/gpt-oss-120b:free

With smart switching enabled:

ai:
  smart-switching: true

MCAIA can move to another configured model when retryable provider failures occur, such as common rate-limit or temporary availability failures.

Provider quotas, model availability, pricing and account access are controlled by the provider and can change at any time.

🛡️ Command safety

MCAIA can execute commands, so command execution is treated as a security-sensitive operation.

The command guard includes built-in restrictions for sensitive operations such as:

stop
restart
restartserver
reload
rl
op
deop
whitelist
ban-ip
pardon-ip
lp
luckperms
pex
permissions
plugman
plugmanx
pluginmanager
function
schedule
sudo

It also detects:

command chaining with ;
newline-separated commands
pipe-based chaining
&& chaining
nested execute ... run ... wrappers
malformed wrappers
namespaced command labels
certain formatting/homoglyph tricks
excessive wrapper depth

You can add server-specific command roots in:

plugins/MCAIA/banned-commands.yml

Important security warning

The command guard is a safeguard, not a complete sandbox.

Do not treat AI access as equivalent to a perfectly isolated environment.

Recommended production practice:

give MCAIA only the permissions it actually needs
keep mcaia.player restricted to trusted users
maintain server backups
review banned-commands.yml
test new models and prompts on a staging server
review logs when diagnosing unexpected behavior
never expose API keys or webhook URLs

👤 Player mode

MCAIA has two main access levels.

Administrator access

mcaia.use

This provides full AI command access.

Player-scoped access

mcaia.player

Player mode is disabled by default.

Enable it:

permissions:
  player-command-mode:
    enabled: true

Then grant:

mcaia.player

In player mode, MCAIA builds a list of commands available to the player and passes the permitted-command context to the AI.

The requested command is still checked against the player's actual permissions before it is dispatched.

Player mode is designed around least privilege. Giving someone mcaia.player should not automatically give them access to commands they could not already use.

🔐 Permission backends

MCAIA works without additional permission plugins.

Supported integrations include:

Bukkit permissions
LuckPerms
Vault
OP/configured-player fallback

If LuckPerms is installed, Bukkit permission checks can use it.

Vault is detected as an alternative permission integration.

When neither is available, MCAIA can use its fallback behavior controlled by:

permissions:
  fallback-require-op: true

You can also explicitly configure permitted players in:

permissions:
  permitted-players:

🌐 Geyser & Floodgate

MCAIA can detect:

Geyser
Floodgate

Bedrock access can be enabled with:

geyser:
  allow-bedrock-players: true

Floodgate's player-name prefix can optionally be removed from logs:

geyser:
  strip-bedrock-prefix: true

Bedrock players use the same MCAIA permission model as Java players.

⌨️ Commands

The default command is:

/ai

The name can be changed with:

command-name: "ai"

A server restart is required after changing it.

Player / user commands

Command	Description
`/ai <prompt>`	Ask a question or request a server action
`/ai help`	Show usage information and examples
`/ai history`	View recent conversation history
`/ai reset`	Clear your conversation history and pending follow-up

Administrative commands

Command	Description
`/aiadmin`	Show administrative help
`/aiadmin status`	Show plugin, provider, permission and integration status
`/aiadmin reload`	Reload MCAIA configuration
`/aiadmin clearhistory <player>`	Clear history for an online player
`/aiadmin clearhistory *`	Clear histories for all online players
`/aiadmin debug`	Toggle debug mode at runtime

The console can use /ai as well.

🔑 Permissions

Permission	Purpose	Default
`mcaia.use`	Full console-level AI command access	Operators
`mcaia.player`	Player-scoped AI access when player mode is enabled	Not granted
`mcaia.admin`	Access to `/aiadmin`	Operators
`mcaia.reload`	Declared reload permission node	Operators
`mcaia.bypass-rate-limit`	Bypass the `/ai` cooldown	Operators
`mcaia.history`	Access to conversation history	Operators
`mcaia.*`	Grants all MCAIA permissions	Not granted

/aiadmin reload currently checks mcaia.admin.

⏱️ Rate limiting

MCAIA has a per-player cooldown to reduce accidental spam and unnecessary API usage.

Default:

rate-limit:
  enabled: true
  cooldown-seconds: 15

Administrators can bypass the cooldown with:

mcaia.bypass-rate-limit

💾 Conversation history

MCAIA keeps conversation context per player so follow-up requests can make sense.

Relevant settings:

ai:
  max-history-length: 10
  query-timeout-seconds: 60

Players can use:

/ai history

to view recent conversation history and:

/ai reset

to clear their own history and pending follow-up.

Administrators can clear online player histories with:

/aiadmin clearhistory <player>

or:

/aiadmin clearhistory *

💬 Follow-up questions

MCAIA can ask a player a follow-up question when the request is incomplete or ambiguous.

For example:

/ai teleport Steve

could require more context depending on the task.

When MCAIA is waiting for a player's answer, their next chat message is handled as a private response instead of being broadcast to the server.

The timeout is configurable:

ai:
  query-timeout-seconds: 60

📋 Configuration files

MCAIA creates its files under:

plugins/MCAIA/

File	Purpose
`config.yml`	Main settings, provider keys, AI options, permissions, rate limits, logging and messages
`models.yml`	Provider and model priority/fallback
`banned-commands.yml`	Additional command roots that should never be executed
`logs/`	Daily plugin log files when file logging is enabled

⚙️ Important configuration

Terms of Service

MCAIA intentionally requires explicit acceptance before processing requests.

tos-accepted: false

Set:

tos-accepted: true

only after reviewing the included terms.

AI limits

ai:
  max-tokens: 2048
  temperature: 0.3
  max-history-length: 10
  query-timeout-seconds: 60
  max-iterations: 8
  smart-switching: true
  command-output-wait-ticks: 30

`max-tokens`

Maximum response token budget.

`temperature`

Controls model randomness.

`max-history-length`

Number of conversation turns retained per player.

`query-timeout-seconds`

How long MCAIA waits for a player's answer to a follow-up question.

`max-iterations`

Maximum internal request → action → result loop iterations.

`smart-switching`

Allows fallback to other configured models after supported retryable provider errors.

`command-output-wait-ticks`

How long MCAIA waits for delayed command output before continuing.

📝 Logging

File logging is enabled by default:

logging:
  file-logging: true

Logs are stored under:

plugins/MCAIA/logs/

Debug mode can be enabled when troubleshooting:

logging:
  debug-mode: true

⚠️ Debug mode warning

Debug mode can write full AI request/response payloads to the console and log file.

Those payloads may contain server data or other sensitive information.

Use debug mode temporarily and disable it afterward.

🔔 Discord admin webhook

MCAIA can optionally notify an administrator Discord webhook about events.

logging:
  admin-webhook-url: ""

Available event types include:

logging:
  log-events:
    - AI_COMMAND_USED
    - COMMAND_EXECUTED
    - COMMAND_REFUSED
    - COMMAND_BLOCKED
    - ERRORS
    - RATE_LIMITED

Keep webhook URLs private.

📊 bStats

MCAIA initializes bStats for anonymous plugin/server metrics.

See the bStats privacy policy for details about the metrics system.

🔒 Privacy

Using MCAIA normally sends prompts and relevant conversation context to the configured AI provider.

Depending on the request, the provider interaction may also include:

supported live server information
player-related server data requested by the AI
command results
conversation history
player-scoped allowed-command information

Command output can become part of the AI conversation.

Treat AI requests, server output, logs, webhook notifications and API credentials as potentially sensitive.

API keys
Bot tokens
Webhook URLs
Passwords
Private credentials
Unredacted sensitive server logs

Always follow the privacy policy and terms of the AI provider you choose.

📦 Installation

Requirements

Paper server
Java 25
A supported AI provider API key

Optional integrations:

LuckPerms
Vault
Geyser
Floodgate

MCAIA can run without the optional integrations.

Install

Download the latest release from GitHub Releases.
Put the JAR into your server's plugins/ directory.
Start the server once.
Open:
```
plugins/MCAIA/config.yml
```
Add at least one provider API key.
Set:
```
tos-accepted: true
```
Restart the server.
Run:
```
/ai help
```
Verify the installation with:
```
/aiadmin status
```

🧪 Recommended first tests

After installation, do not immediately give MCAIA broad access.

Start with read-only requests.

Test 1 — Players

/ai how many players are online?

Test 2 — TPS

/ai show me the server TPS

Test 3 — Worlds

/ai list the worlds on this server

Test 4 — Plugins

/ai list the plugins installed on this server

Test 5 — Player information

/ai tell me information about Steve

Then test a safe multi-step workflow on a test server.

🎬 Demo

🐛 Troubleshooting

MCAIA says it is disabled

Check:

tos-accepted: true

Then restart the server.

No provider is configured

Make sure at least one API key is present in:

plugins/MCAIA/config.yml

Then verify:

/aiadmin status

Provider authentication error

Check:

API key
provider name
provider account
model availability
API access permissions

Do not paste your API key into Discord support.

Rate limited

A provider may return a rate-limit response.

Check your provider quota and consider configuring multiple providers/models in models.yml.

A command is refused

Check:

Your permissions
mcaia.player player mode rules
banned-commands.yml
MCAIA's built-in command guard
The server console/logs

Some commands are intentionally blocked and cannot simply be enabled through the normal blocklist.

AI gives incorrect information

AI models can make mistakes.

Try:

a more specific prompt
asking MCAIA to query current server state
using a stronger model
configuring a fallback provider
testing the request manually

Do not treat an AI response as proof that an action succeeded.

🐛 Reporting a bug

A useful bug report should contain:

Environment

MCAIA version:
Minecraft version:
Paper version:
Java version:
Other relevant plugins:

Reproduction

What did you do?
What prompt or command did you use?

Expected result

What should have happened?

Actual result

What happened instead?

Logs

Attach only the relevant logs.

Remove:

API keys
webhook URLs
tokens
passwords
sensitive player information
private infrastructure details

💡 Feature requests

Good feature requests explain the problem, not only the desired command.

A strong request answers:

What is difficult today?
Who has the problem?
What would the ideal workflow look like?
Where would AI actually help?
Can you provide a realistic example prompt?

Example:

Server owners often need to inspect several pieces of server state before taking one action. It would be useful if MCAIA could summarize those values in one structured response.

That gives the project something concrete to design around.

🧑‍💻 Development

Clone the repository:

git clone https://github.com/TIS199/MCAIA.git
cd MCAIA

The project includes the Gradle wrapper.

Build:

./gradlew build

On Windows:

gradlew.bat build

The distributable JAR is generated under:

build/libs/

Before submitting changes:

./gradlew build

Make sure the project still builds successfully.

🤝 Contributing

Contributions are welcome.

Useful contributions include:

bug fixes
documentation
tests
compatibility improvements
provider improvements
security reviews
translations
example configurations
troubleshooting guides
feature proposals

For larger changes, open an issue first so the implementation can be discussed before development time is spent.

Please keep pull requests focused and include testing notes.

📌 Project status

MCAIA is actively developed.

Features, configuration and behavior can change between releases.

For production servers:

Back up first. Test first. Give the AI only the access it actually needs.

🔗 Links

📄 License

MCAIA is licensed under GNU GPL-3.0-only.

See the LICENSE file for the complete license text.

MCAIA

Ask for the result. MCAIA handles the Minecraft-side work.

Pages

Resource Page

Wiki

MCAIA

MCAIA Wiki

What is MCAIA?

✨ Features

💬 Natural-language administration

🔎 Live server information

🔁 Multi-step AI workflows

🧠 Supported AI providers

🔄 Provider & model fallback

🛡️ Command safety

Important security warning

👤 Player mode

Administrator access

Player-scoped access

🔐 Permission backends

🌐 Geyser & Floodgate

⌨️ Commands

Player / user commands

Administrative commands

🔑 Permissions

⏱️ Rate limiting

💾 Conversation history

💬 Follow-up questions

📋 Configuration files

⚙️ Important configuration

Terms of Service

AI limits

max-tokens

temperature

max-history-length

query-timeout-seconds

max-iterations

smart-switching

command-output-wait-ticks

📝 Logging

⚠️ Debug mode warning

🔔 Discord admin webhook

📊 bStats

🔒 Privacy

Never share

📦 Installation

Requirements

Install

🧪 Recommended first tests

Test 1 — Players

Test 2 — TPS

Test 3 — Worlds

Test 4 — Plugins

Test 5 — Player information

🎬 Demo

💬 Natural-language administration

🧠 Live server intelligence

⚡ Multi-step AI workflow

🐛 Troubleshooting

MCAIA says it is disabled

No provider is configured

Provider authentication error

Rate limited

A command is refused

AI gives incorrect information

🐛 Reporting a bug

Environment

Reproduction

Expected result

Actual result

Logs

💡 Feature requests

🧑‍💻 Development

🤝 Contributing

📌 Project status

🔗 Links

📄 License

Pages

`max-tokens`

`temperature`

`max-history-length`

`query-timeout-seconds`

`max-iterations`

`smart-switching`

`command-output-wait-ticks`