Minecraft Builder MCP

Let Claude or Codex build in your Minecraft world — live, while you watch.

English · Русский

Every frame above is a real MCP tool call on a real Minecraft 26.3 server.

You say "build a lighthouse on that little island" — the AI calls fill / place_blocks, the blocks appear in your game, the AI renders a picture to check its own work, and fixes what looks off. It can also write minigames as datapacks and hot-reload them while you play, then hand the world back to you for Realms.

• 🧱 Builds fast — server commands via RCON, thousands of blocks per call (not a bot placing blocks one by one)

• 👀 Sees the world — reads blocks from the world files and renders textured previews so the AI can check its work

• 🏗️ Whole buildings in one call — draw it as ASCII layers (build_layers); huge procedural terrain via scripts

• 🎯 Knows where you look — "put it here" works: position, facing and the block under your crosshair

• 🎮 Writes minigames — datapack functions with /reload, errors read back from the log

• 🌍 Realms-ready — export the world to singleplayer, upload to Realms

• 🔌 Zero setup — runs the server from your installed game, auto-detects Java and version; no downloads, no mods

• 🤝 Claude Code, Claude Desktop and Codex — one python install.py

Bundled map: Sky Gardens

A procedurally generated floating-island lobby comes with the repo and loads on first start — a giant tree plaza with four themed islands linked by rope bridges, above a sea of clouds.

Related MCP server: minecraft-rcon-mcp

How it works

 you: "build a bridge here"      AI calls a tool         this MCP server         Minecraft server
 ───────────────────────────▶   fill(...)        ───▶   (mcp_minecraft)  ─RCON─▶ on your computer
                                                                                       │
 you see the bridge appear in-game (Multiplayer → localhost)  ◀─────────────────────────┘

• MCP (Model Context Protocol) gives the AI tools — "place blocks", "where is the player", "render this area".

• The Minecraft server is started from the game you already have installed (the client jar ships the dedicated server). It listens on 127.0.0.1 only.

• RCON is the server's remote console: the AI runs the same commands you would type in chat.

Requirements

1. Minecraft Java Edition (official launcher). Launch the version you want once — that downloads the game files and the right Java. The newest installed release is used by default (Sky Gardens is made for 26.3).

2. Python 3.10+ (python.org; on Windows tick Add Python to PATH).

3. One of: Claude Code, Claude Desktop, or Codex.

Install

git clone https://github.com/3-03/minecraft-builder-mcp.git

cd minecraft-builder-mcp

python install.py

install.py installs numpy + Pillow and registers the minecraft MCP server in every client it finds:

Config files are backed up first (*.bak-<date>). Only one client: --codex / --claude-desktop. Show the config without changing anything: python install.py --print. Moved the folder? Run it again.

Codex:

codex mcp add minecraft --env PYTHONIOENCODING=utf-8 -- python /path/to/repo/mcp_minecraft/mcp_server.py

then add tool_timeout_sec = 300 under [mcp_servers.minecraft] in ~/.codex/config.toml.

Claude Code, available in every project:

claude mcp add minecraft --scope user -- python /path/to/repo/mcp_minecraft/mcp_server.py

On macOS/Linux use python3 if python is not found (also in .mcp.json).

Use

1. Ask: "start the Minecraft server". On first start the Sky Gardens map is loaded.

2. In Minecraft (same version): Multiplayer → Direct Connection → localhost.

3. Talk to it:

   • "what am I looking at?" / "put a gazebo here"

   • "make a 40×40 PvP arena south of the island"

   • "show me a picture of the whole map"

   • "make a minigame: first to reach the flag on the volcano wins"

   You can also type in the in-game chat — the AI reads it.

4. Done? "export the world" → it appears in singleplayer → Realms → Configure → Replace world.

Tools

Fences, walls and panes are connected automatically and leaves never decay unless asked to.

Big procedural builds

Tool calls are perfect for buildings. For organic terrain — islands, mountains, forests — an agent with a shell (Claude Code, Codex) writes a generator script and streams the result to the live server with mc.place_array: runs of blocks become /fill, so thousands of blocks land in about a second.

import sys; sys.path.insert(0, 'mcp_minecraft'); import mc
mc.place_array(x0, y0, z0, ids, ['air', 'stone', 'grass_block', 'oak_leaves'])  # ids: numpy [x, y, z]

Try it: python examples/floating_island.py drops a floating island with a tree in front of you. The bundled map itself was made the same way, offline — see mapgen/.

Troubleshooting

Ask "check the Minecraft server status" — server_status shows the detected version, Java path and what's wrong.

Environment variables can go in the "env" block of .mcp.json / your client config.

FAQ

Does it work in singleplayer? Not for live building: the singleplayer built-in server has no RCON. The local server feels the same (only you, creative, your world) — and world_export turns it back into a singleplayer world.

Can friends join? The server only listens on 127.0.0.1. To let friends in, use a tunnel such as playit.gg pointed at 127.0.0.1:25565 (keeps RCON private), turn on a whitelist and, if everyone owns the game, set online-mode=true. Never expose the RCON port (25575).

Why not a bot like Mineflayer? Bots place blocks one by one like a player and lag behind new game versions. Server commands are instant and work on the newest version.

Project layout

mcp_minecraft/   the MCP server: mcp_server.py (tools), mc.py (server, RCON, world reader, place_array),
                 isorender.py (textured renderer)
examples/        scripts for big builds on the live server
maps/            bundled maps (.zip), listed by world_list
mapgen/          procedural generator of Sky Gardens (numpy) — see mapgen/README.md
docs/            README images; make_images.py / make_demo.py regenerate them
tests/           unit tests (no Minecraft needed)
mcserver/        created on first start: world, logs, backups, RCON password (git-ignored)

Safety notes

• The server binds to 127.0.0.1; online-mode=false so any launcher account can join locally.

• The RCON password is random per install and stays in mcserver/server.properties.

• First start writes mcserver/eula.txt = agreeing to the Minecraft EULA (the same one you accepted for the game) — the server won't start without it.

• world_import backs up the previous server world; world_export never overwrites your own saves.

• Realms can't be controlled directly (no RCON) — build locally, then upload.

License

MIT. Not an official Minecraft product; not approved by or associated with Mojang or Microsoft.