Minecraft Server MCP

English | 日本語

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

Configuration & World Generation

World Management

Commands

Player Management

Backup & Restore

Resources (read-only data)

Setup

Prerequisites

• Node.js >= 20.0.0
• Java (for running the Minecraft server)
• Minecraft Java Edition server JAR (download)

Install

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

Download the Server JAR

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:

{
  "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:

{
  "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

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

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

License

MIT