Minecraft MCP Build Server

An MCP (Model Context Protocol) server that generates and places Minecraft structures from natural language descriptions. Describe what you want — a medieval castle, a futuristic skyscraper, a Greek temple — and the server interprets, plans, and builds it block-by-block in a live Minecraft world.

Architecture

prompt (natural language)
    |
    v
PromptInterpreter       rule-based keyword extraction
    |
    v
StructurePlanner        dimensions, materials, constraints
    |
    v
HierarchicalGenerator   voxel-level structure generation
    |
    v
VoxelGrid               sparse 3D block grid
    |
    v
BotClient / GDMCClient  block placement in Minecraft

Placement methods:

| Method | How it works | |--------|-------------| | Mineflayer bot (preferred) | A bot joins the world as a player and executes /fill commands. Builds are visible in real time. | | GDMC HTTP (fallback) | Direct block placement via the GDMC HTTP Interface mod. Silent, no player needed. |

The server automatically falls back from bot to GDMC if the bot is unavailable.

Supported structures

Houses, cottages, mansions, castles, towers, skyscrapers, temples, lighthouses, dungeons, villages, cities, and 60+ specific building types (cinema, hospital, stadium, airport, etc.).

Supported styles

Medieval, modern, futuristic, gothic, Japanese, Greek, rustic, classic — each with a distinct material palette.

Features

Moats, towers, gardens, pools, battlements, balconies, basements, courtyards, spires, neon lights, glass roofs, drawbridges, lanterns, and more. Requested via natural language.

Requirements

• Python 3.12+
• Node.js 18+ (for the Mineflayer bot)
• Minecraft Java Edition with either:
  • LAN world open (for bot placement), or
  • GDMC HTTP Interface mod installed

Setup

# Install Python dependencies
pip install -r requirements.txt

# Install bot dependencies
cd bot && npm install && cd ..

Usage

Stdio transport (local MCP clients)

python main.py

Add to your MCP client config (see mcp_client_config.example.json):

{
  "mcpServers": {
    "minecraft-builder": {
      "command": "python3",
      "args": ["/path/to/minecraftmcp/main.py"],
      "env": {
        "GDMC_HOST": "localhost",
        "GDMC_PORT": "9000"
      }
    }
  }
}

HTTP transport (remote MCP clients)

python main_http.py

Expose via HTTPS for remote access:

ngrok http 8000

Point your MCP client at https://<your-domain>/mcp.

Mineflayer bot

node bot/bot.js

The bot connects to your Minecraft server and places blocks as a visible player. Open your world to LAN first.

MCP Tools

| Tool | Description | |------|-------------| | generate_and_build | Build a structure from a natural language prompt. Accepts optional location coordinates and scale multiplier (0.25 - 4.0). | | ping_gdmc | Check connectivity to the bot and GDMC mod. |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | GDMC_HOST | localhost | GDMC HTTP mod host | | GDMC_PORT | 9000 | GDMC HTTP mod port | | MCP_HTTP_HOST | 0.0.0.0 | HTTP server bind address | | MCP_HTTP_PORT | 8000 | HTTP server port | | MC_HOST | localhost | Minecraft server host (bot) | | MC_PORT | 25565 | Minecraft server port (bot) | | BOT_NAME | Builder | Bot in-game username | | LOG_LEVEL | INFO | DEBUG, INFO, or WARNING | | DEBUG_VISUALIZE | 0 | Set to 1 for ASCII structure preview |

License

MIT