# ⛏️ Minecraft RCON MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-green.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](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)