⛏️ Minecraft RCON MCP Server

License: MIT

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 Server