Minecraft RCON MCP Server

⛏️ Minecraft RCON MCP Server

An MCP (Model Context Protocol) server that connects AI agents to Minecraft servers through RCON. Execute commands, monitor logs, query databases, and check plugin health — all from your AI coding assistant.

Built and battle-tested during real AI-assisted Minecraft plugin development.

Features

• RCON Command Execution — Run any server command with automatic reconnection on failure
• Command + Log Capture — Execute a command and capture the server log output that follows (unique and powerful for plugin debugging)
• Server Log Reading — Tail the latest server log
• Filtered Log Monitoring — Read logs by configurable prefix (e.g. [TEST], [DEBUG]) with incremental position tracking for efficient polling
• SQLite Database Queries — Safe read-only SELECT queries against plugin databases, with write-operation blocking
• Plugin Health Checks — Combined RCON connectivity + error log scan + database status in one call

Quick Start

1. Install

# From PyPI (when published)
pip install minecraft-rcon-mcp

# Or from source
git clone https://github.com/YOUR_USERNAME/minecraft-rcon-mcp.git
cd minecraft-rcon-mcp
pip install .

2. Configure

Copy .env.example to .env and fill in your server details:

cp .env.example .env

RCON_HOST=localhost
RCON_PORT=25575
RCON_PASSWORD=your_password
SERVER_DIR=/path/to/minecraft/server

# Optional
DATABASE_PATH=/path/to/plugin.db
LOG_PREFIX=[TEST]

Make sure RCON is enabled in your server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your_password

3. Run

# Direct
minecraft-rcon-mcp

# Or as a module
python -m minecraft_rcon_mcp

Configuration

Tools

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "minecraft-rcon": {
      "command": "minecraft-rcon-mcp",
      "env": {
        "RCON_HOST": "localhost",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "your_password",
        "SERVER_DIR": "/path/to/minecraft/server",
        "DATABASE_PATH": "/path/to/plugin.db"
      }
    }
  }
}

Usage with Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "minecraft-rcon": {
      "command": "minecraft-rcon-mcp",
      "env": {
        "RCON_HOST": "localhost",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "your_password",
        "SERVER_DIR": "/path/to/minecraft/server",
        "DATABASE_PATH": "/path/to/plugin.db"
      }
    }
  }
}

Find your server.properties

rcon.password= rcon.port= enable-rcon=true

Use Cases

AI-Assisted Plugin Testing

The run_command_with_log + read_test_log combo enables a powerful automated testing loop:

Agent writes plugin code
    → Build & deploy to server
    → run_command_with_log("mytest run")
    → read_test_log(event_filter="FAIL")
    → Agent fixes failures
    → Repeat

Live Debugging

check_plugin_status()           → Is the plugin loaded? Any errors?
run_command("mycommand arg")    → Execute plugin commands
read_server_log(lines=100)      → Check what happened
query_database("SELECT ...")    → Inspect plugin data

Incremental Log Monitoring

# First call — read all test logs
result = read_test_log()  # returns position=12345

# After running more tests — only get NEW entries
result = read_test_log(since_position=12345)