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

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

Setup

Getting a Gemini API Key

1. Go to Google AI Studio
2. Click "Create API Key"
3. Copy your API key

Configuring the Plugin

1. In-game, run: /g setapikey YOUR_API_KEY_HERE
2. 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

1. Context Gathering: When you ask a question, the plugin gathers current server information:

   • Players online
   • World data
   • Server performance (TPS, memory)
   • Recent chat messages

2. AI Processing: Your question and context are sent to Gemini AI

3. Response Parsing: The AI's response is analyzed for command suggestions

4. Command Execution: If commands are suggested:

   • In normal mode: You're asked to confirm
   • In auto-accept mode: Commands execute automatically

5. 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

1. Clone the repository
2. Install Maven
3. Run: mvn clean package
4. 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.