Minecraft RCON

Connects AI agents to Minecraft via RCON, enabling command execution, log capture, log filtering, and safe database queries from an MCP client.

python

GitHub Stars

python

Language

2 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can connect AI agents to a running Minecraft server via RCON using this MCP server. It lets you execute server commands, tail and filter logs, run safe read-only queries against plugin databases, and perform integrated health checks of your RCON connection, logs, and data sources, all from your AI coding environment.

How to use

You use an MCP client to communicate with the server through the provided tools. Send commands to the Minecraft server, capture subsequent log output for debugging, and query the plugin database in a read-only fashion. You can also monitor server health, including RCON connectivity and recent error logs, in a single call to simplify automated testing and debugging workflows.

How to install

Prerequisites: Python is installed on your system. You may also want to ensure you have a Python package manager available (pip). You will run two simple setup flows to install and run the MCP server client.

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

Configuration

Prepare the environment by setting the required values in your environment or in a .env file. The essential settings include the RCON connection details and the server directory for the Minecraft instance. Optional values control database access and log filtering.

# Example environment variables you will use
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 your Minecraft server has RCON enabled with a matching port and password. In server.properties set:

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

Use cases

Common scenarios include AI-assisted plugin testing, live debugging, and incremental log monitoring. You can run a command and immediately fetch the following server log to verify behavior, or tail the log with a prefix filter to focus on relevant events. You can also perform safe database queries to inspect plugin data without risking writes.

Development

If you are developing against the MCP server, install dependencies in editable mode and run the server client from source to iterate quickly.

git clone https://github.com/YOUR_USERNAME/minecraft-rcon-mcp.git
cd minecraft-rcon-mcp
pip install -e .

Available tools

run_command

Execute an RCON command on the server. Returns the result or output status.

run_command_with_log

Execute a command and capture the subsequent server log output for debugging and verification.

read_server_log

Read the last N lines from the server log to monitor recent activity.

read_test_log

Read logs filtered by a specific prefix with incremental position tracking for efficient polling.

query_database

Execute a safe read-only SELECT query against the plugin SQLite database.

check_plugin_status

Check RCON connectivity, recent errors, and database status in one call.

Built by

VeilStrat

AI signals for GTM teams