# ⛏️ Minecraft RCON MCP Server
[](LICENSE)
[](https://python.org)
[](https://modelcontextprotocol.io)
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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
```bash
# 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:
```bash
cp .env.example .env
```
```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`:
```properties
enable-rcon=true
rcon.port=25575
rcon.password=your_password
```
### 3. Run
```bash
# 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`:
```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`:
```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
```python
# 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
```bash
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](LICENSE)
