# Minecraft Server MCP

**English** | [日本語](./README.ja.md)

An MCP (Model Context Protocol) server for **Minecraft Java Edition server administration**. Lets AI directly manage world generation, server configuration, player management, and more.

> Unlike existing Minecraft MCP servers that focus on bot movement via Mineflayer, this project provides **server administrator-level** control — world generation, `server.properties` editing, RCON commands, NBT data, backups, and full player management.

## Features

- **Server Lifecycle** — Start / stop / restart / status monitoring
- **World Generation** — Seeds, world types (normal, flat, amplified, large biomes), superflat config
- **Configuration** — Read/write all `server.properties` settings
- **RCON Commands** — Execute any server command remotely
- **World Data** — Read/write `level.dat` via NBT parsing
- **Player Management** — OP, ban, whitelist, gamemode, effects
- **Backup & Restore** — Compressed backups with safe hot-backup (save-off/save-on)
- **Building** — setblock, fill, summon, teleport, give
- **Game Rules** — keepInventory, doDaylightCycle, mobGriefing, etc.

## Tools (40)

### Server Management
| Tool | Description |
|------|-------------|
| `start_server` | Start the server (auto EULA acceptance) |
| `stop_server` | Graceful shutdown via RCON → stdin → SIGKILL |
| `restart_server` | Restart the server |
| `server_status` | Running state, uptime, online players, MOTD |
| `server_logs` | Recent console output |
| `validate_server` | Check JAR, EULA, RCON configuration |
| `configure_mcp` | Update MCP runtime config |

### Configuration & World Generation
| Tool | Description |
|------|-------------|
| `get_server_properties` | Read all settings with descriptions |
| `set_server_property` | Set a single property |
| `set_server_properties_bulk` | Set multiple properties at once |
| `setup_world` | Configure world generation (seed, type, gamemode, difficulty, structures) |
| `get_game_rules` | List all game rules via RCON |
| `set_game_rule` | Set a game rule |

### World Management
| Tool | Description |
|------|-------------|
| `list_worlds` | List worlds with size, seed, game type |
| `get_world_info` | Detailed level.dat info (NBT parsed) |
| `delete_world` | Delete a world (confirmation required) |
| `set_world_spawn` | Modify spawn point in level.dat |

### Commands
| Tool | Description |
|------|-------------|
| `execute_command` | Run any server command via RCON |
| `execute_commands` | Batch execute multiple commands |
| `set_time` | Set time (presets: day, noon, sunset, night, midnight, sunrise) |
| `set_weather` | Set weather (clear, rain, thunder) |
| `set_block` | Place a block at coordinates |
| `fill_blocks` | Fill a region with blocks |
| `summon_entity` | Summon an entity with optional NBT |
| `teleport` | Teleport players/entities |
| `give_item` | Give items to players |

### Player Management
| Tool | Description |
|------|-------------|
| `list_players` | Online players and max count |
| `op_player` / `deop_player` | Grant/revoke operator |
| `kick_player` / `ban_player` / `pardon_player` | Moderation |
| `whitelist_manage` | Add, remove, on, off, reload |
| `set_gamemode` | Change player game mode |
| `apply_effect` | Apply status effects |
| `list_ops` | List operators from ops.json |

### Backup & Restore
| Tool | Description |
|------|-------------|
| `create_backup` | Create compressed tar.gz backup (hot-backup safe) |
| `list_backups` | List all backups |
| `restore_backup` | Restore from backup (auto safety-backup before overwrite) |
| `delete_backup` | Delete a backup |

### Resources (read-only data)
| URI | Description |
|-----|-------------|
| `minecraft://server/status` | Server status as JSON |
| `minecraft://server/properties` | Current server.properties as JSON |
| `minecraft://server/worlds` | World list with info |
| `minecraft://server/logs` | Recent console output |

## Setup

### Prerequisites
- **Node.js** >= 20.0.0
- **Java** (for running the Minecraft server)
- **Minecraft Java Edition server JAR** ([download](https://www.minecraft.net/en-us/download/server))

### Install

```bash
git clone https://github.com/tamo2918/Minecraft-Server-MCP.git
cd Minecraft-Server-MCP
npm install
npm run build
```

### Download the Server JAR

```bash
mkdir -p minecraft-server
cd minecraft-server
# Download the latest server JAR from https://www.minecraft.net/en-us/download/server
# Place server.jar in this directory
```

## Usage

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "/path/to/minecraft-server-mcp/dist/index.js",
        "--server-dir", "/path/to/minecraft-server",
        "--rcon-password", "your_secure_password"
      ]
    }
  }
}
```

### Claude Code

Add to `.claude/settings.json` or `~/.claude.json`:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "/path/to/minecraft-server-mcp/dist/index.js",
        "--server-dir", "/path/to/minecraft-server",
        "--rcon-password", "your_secure_password"
      ]
    }
  }
}
```

### Environment Variables

```bash
export MC_SERVER_DIR="/path/to/minecraft-server"
export MC_RCON_PASSWORD="your_secure_password"
export MC_BACKUP_DIR="/path/to/backups"
node dist/index.js
```

### CLI Options

```
--server-dir <path>      Minecraft server directory (default: ./minecraft-server)
--server-jar <filename>  Server JAR filename (default: server.jar)
--java-path <path>       Java executable (default: java)
--jvm-args <args>        JVM arguments (default: "-Xmx2G -Xms1G")
--rcon-host <host>       RCON host (default: localhost)
--rcon-port <port>       RCON port (default: 25575)
--rcon-password <pass>   RCON password
--backup-dir <path>      Backup directory (default: ./backups)
```

## Examples

Tell your AI things like:

```
"Generate a flat world with seed 12345 in creative mode"
  → setup_world + restart_server

"Give all players a diamond sword"
  → give_item(@a, diamond_sword, 1)

"Fill 0,64,0 to 10,70,10 with diamond blocks"
  → fill_blocks(0, 64, 0, 10, 70, 10, diamond_block)

"Set weather to clear and time to noon"
  → set_weather(clear) + set_time(noon)

"Backup the current world, then generate a new one"
  → create_backup + setup_world + delete_world + restart_server

"Turn on keepInventory"
  → set_game_rule(keepInventory, true)
```

## Architecture

```
src/
  index.ts                    # MCP server entry point + CLI arg parsing
  core/
    types.ts                  # Shared type definitions
    RconClient.ts             # RCON connection management
    ServerProperties.ts       # server.properties parser/writer
    ServerManager.ts          # Server process lifecycle
    WorldManager.ts           # World file operations (NBT)
    BackupManager.ts          # Backup/restore with tar.gz
  tools/
    server-tools.ts           # Server lifecycle tools
    config-tools.ts           # Configuration & game rule tools
    world-tools.ts            # World management tools
    command-tools.ts          # RCON command tools
    player-tools.ts           # Player management tools
    backup-tools.ts           # Backup tools
  resources/
    server-resources.ts       # MCP resource definitions
```

## How It Works

1. **Server Management**: Spawns the Minecraft server as a child process, captures stdout/stderr, waits for "Done" on startup
2. **RCON**: Connects to the server's RCON port for runtime command execution (requires `enable-rcon=true` in server.properties — auto-configured)
3. **Configuration**: Directly reads/writes `server.properties` as a text file, preserving comments
4. **World Data**: Parses `level.dat` using prismarine-nbt for reading seed, spawn point, game type, version info
5. **Backups**: Uses `tar -czf` for compression, with `save-off`/`save-on` RCON commands for hot backups

## Compared to Other Minecraft MCPs

| Feature | This Project | mcp-minecraft | mcp-minecraft-remote |
|---------|-------------|---------------|---------------------|
| Server start/stop | Yes | Yes | No |
| server.properties editing | Yes | No | No |
| World generation config | Yes | No | No |
| level.dat NBT parsing | Yes | No | No |
| Backup/restore | Yes | No | No |
| RCON commands | Yes | No | No |
| Game rules | Yes | No | No |
| Player management | Yes | Limited | Limited |
| Bot movement | No | Yes | Yes |
| Block mining/placing (bot) | No | Yes | Yes |
| Crafting/trading | No | No | Yes |

This project is **complementary** to bot-based MCPs — use both together for full AI control.

## License

MIT