⛏️ Minecraft RCON MCP Server

![License: MIT](LICENSE) ![Python 3.11+](https://python.org) ![MCP](https://modelcontextprotocol.io)

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

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | RCON_HOST | No | localhost | RCON server hostname | | RCON_PORT | No | 25575 | RCON server port | | RCON_PASSWORD | Yes | — | RCON password | | SERVER_DIR | Yes | — | Minecraft server root directory | | DATABASE_PATH | No | — | Path to plugin SQLite database | | LOG_PREFIX | No | [TEST] | Prefix for filtered log reading |

---

Tools

| Tool | Description | Read-Only | |------|-------------|-----------| | run_command | Execute an RCON command on the server | No | | run_command_with_log | Execute a command and capture subsequent server log output | No | | read_server_log | Read the last N lines from the server log | Yes | | read_test_log | Read prefix-filtered log entries with incremental position tracking | Yes | | query_database | Execute a read-only SELECT query on the plugin SQLite database | Yes | | check_plugin_status | Check RCON connectivity, recent errors, and database status | Yes |

---

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)

---

Development

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

---

中文说明

这是一个 MCP (Model Context Protocol) 服务器，通过 RCON 协议将 AI Agent 连接到 Minecraft 服务器。

核心功能

RCON 命令执行 — 支持自动重连
命令 + 日志捕获 — 执行命令后自动抓取服务器日志输出
日志过滤读取 — 按前缀过滤日志，支持增量读取（位置追踪）
数据库只读查询 — 安全的 SQLite SELECT 查询，自动拦截写操作
插件健康检查 — RCON 连通性 + 错误日志 + 数据库状态一键检查

典型工作流

AI Agent 编写插件代码
    → 构建部署到服务器
    → run_command_with_log("cvtest all")     ← 执行测试
    → read_test_log(event_filter="SUMMARY")  ← 查看结果
    → read_test_log(event_filter="FAIL")     ← 查看失败详情
    → Agent 修复问题 → 重复

这个 MCP 服务器在真实的 AI 辅助 Minecraft 插件开发中经过了充分验证（248 个测试用例全部通过）。

---

License

MIT

Minecraft-RCON-MCP