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

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)

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

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