GeminiMC

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

- Dual Model Support: Ask Gemini questions in plain English - Dual Model Support: AI can suggest and execute server commands - Dual Model Support: Review commands before execution (or enable auto-accept) - Dual Model Support: Maintains chat history for context-aware responses - Dual Model Support: AI has access to server info, player data, and recent chat - Dual Model Support: 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`:

```yaml

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

- No External Access: Only server operators can use `/g` commands - No External Access: All commands can be reviewed before execution (unless auto-accept is enabled) - No External Access: 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

```bash 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.