Minecraft RCON Server

License: MIT Python 3.11+ MCP

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