GeminiMC - Gemini AI for Minecraft Server Management

A powerful Minecraft plugin that integrates Google's Gemini AI to help server administrators manage their servers through natural language commands.

Features

Natural Language Interface: Ask Gemini questions in plain English
Command Execution: AI can suggest and execute server commands
Confirmation System: Review commands before execution (or enable auto-accept)
Conversation Memory: Maintains chat history for context-aware responses
Server Context: AI has access to server info, player data, and recent chat
OP-Only Access: Secure - only server operators can use the plugin
Dual Model Support: Uses Gemini 2.0 Flash for both planning and execution

Requirements

Minecraft 1.21+ (Spigot/Paper server)
Java 21 or higher
Google Gemini API key

Installation

Download the plugin JAR file
Place it in your server's plugins folder
Restart your server
Configure your API key (see Setup section)

Setup

Getting a Gemini API Key

Go to Google AI Studio
Click "Create API Key"
Copy your API key

Configuring the Plugin

In-game, run: /g setapikey YOUR_API_KEY_HERE
Or edit plugins/GeminiMC/config.yml and add your key there

Usage

Basic Commands

/g <question>              - Ask Gemini AI a question
/g setapikey <key>         - Set your Gemini API key
/g autoaccept <true|false> - Toggle auto-accepting commands
/g clearhistory            - Clear conversation history
/g context view            - View current server context
/g context clear           - Clear recent chat context
/g confirm                 - Confirm pending commands
/g cancel                  - Cancel pending commands
/g help                    - Show help message

Example Usage

Basic Questions

/g how many players are online?
/g what time is it in the overworld?
/g how much memory is the server using?

Server Management

/g give all online players a diamond
/g teleport everyone to spawn
/g change the weather to clear
/g set the time to day in all worlds

Complex Tasks

/g create a new world called "mining" with seed 12345
/g ban player xyz for griefing
/g give op to player abc

Command Confirmation

When Gemini suggests commands, you'll see:

⚠ The AI wants to execute the following commands:
  • /give @a diamond 1
  • /say Diamonds for everyone!

[CONFIRM]  [CANCEL]

Click the buttons or type /g confirm or /g cancel.

Auto-Accept Mode

For trusted operations, enable auto-accept:

/g autoaccept true

Commands will execute immediately without confirmation. Be careful with this mode!

To disable:

/g autoaccept false

How It Works

Context Gathering: When you ask a question, the plugin gathers current server information:
- Players online
- World data
- Server performance (TPS, memory)
- Recent chat messages
AI Processing: Your question and context are sent to Gemini AI
Response Parsing: The AI's response is analyzed for command suggestions
Command Execution: If commands are suggested:
- In normal mode: You're asked to confirm
- In auto-accept mode: Commands execute automatically
History Tracking: The conversation is saved for future context

Configuration

Edit plugins/GeminiMC/config.yml:

# Your Gemini API key
api-key: ""

# Auto-accept command execution
auto-accept: false

# Maximum chat history to keep
max-history: 50

# Maximum recent chat messages to include in context
max-chat-context: 10

# Gemini API settings
gemini:
  planning-model: "gemini-2.0-flash-exp"
  execution-model: "gemini-2.0-flash-exp"
  api-url: "https://generativelanguage.googleapis.com/v1beta/models/"

Security

OP-Only: Only server operators can use /g commands
Command Review: All commands can be reviewed before execution (unless auto-accept is enabled)
Console Execution: Commands run as console with full permissions
No External Access: The AI cannot access external services beyond the Gemini API

Building from Source

Clone the repository
Install Maven
Run: mvn clean package
Find the JAR in target/GeminiMC-1.0.0.jar

Build Requirements

Java 21 JDK
Maven 3.6+

Build Command

mvn clean package

Troubleshooting

"API key not set" error

Run /g setapikey YOUR_KEY in-game
Or add the key to config.yml

Commands not executing

Make sure you're an OP: /op yourname
Check server logs for errors
Verify your API key is valid

AI not responding

Check your internet connection
Verify the Gemini API is accessible
Check server console for error messages

"You must be an operator" message

Only OPs can use this plugin
Ask a server admin to OP you: /op yourname

Privacy & Data

Conversation history is stored locally in plugins/GeminiMC/histories/
Questions and context are sent to Google's Gemini API
No data is sent to any other external service
Review Google's Gemini API Terms of Service

Support

For issues, questions, or suggestions:

Check the troubleshooting section above
Review server console logs
Check that you're using a compatible Minecraft version (1.21+)

License

This plugin is provided as-is for server management purposes.

Credits

Built with Paper API
Powered by Google Gemini AI
Uses OkHttp for HTTP requests
Uses Gson for JSON processing

Version

Current version: 1.0.0

Note: This plugin gives AI the ability to execute server commands. Always review commands before confirming unless you fully trust the AI's suggestions. Use auto-accept mode with caution.

GeminiMC