<div align="center">

# Minecraft Builder MCP

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

[![tests](https://github.com/3-03/minecraft-builder-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/3-03/minecraft-builder-mcp/actions/workflows/tests.yml)
![Minecraft Java 26.x](https://img.shields.io/badge/Minecraft-Java%2026.x-62B47A)
![MCP](https://img.shields.io/badge/MCP-stdio-7B61FF)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB)
![no deps](https://img.shields.io/badge/deps-numpy%20%2B%20Pillow-lightgrey)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

**English** · [Русский](README.ru.md)

<img src="docs/demo.gif" width="760" alt="An AI builds a lighthouse through MCP, step by step">

<sub>Every frame above is a real MCP tool call on a real Minecraft 26.3 server.</sub>

</div>

---

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.

<img src="docs/hero.png" alt="Sky Gardens map overview">

<img src="docs/islands.png" alt="Cherry Grove, Frost Peak, Oasis and Volcano islands">

<details>
<summary>Lobby close-up</summary>

<img src="docs/lobby.png" alt="Central lobby with the giant tree, waterfall and bridges">
</details>

## 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](https://www.python.org/downloads/); on Windows tick *Add Python to PATH*).
3. One of: **Claude Code**, **Claude Desktop**, or **Codex**.

## Install

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

```bash
cd minecraft-builder-mcp
```

```bash
python install.py
```

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

| Client | What happens |
|---|---|
| **Claude Code** | nothing needed — open Claude Code **in this folder**, `.mcp.json` is picked up; approve `minecraft` |
| **Codex** | added to `~/.codex/config.toml` (with a longer tool timeout for the first server start) |
| **Claude Desktop** | added to `claude_desktop_config.json` — restart the app |

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.

<details>
<summary>Manual setup</summary>

Codex:

```bash
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:

```bash
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`).
</details>

## 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

| Tool | What it does |
|---|---|
| `server_start` · `server_stop` · `server_status` | run the local server; status also diagnoses setup (version, Java) |
| `run_command` · `run_commands` | any server command |
| `fill` | fill a box of any size (auto-split, chunks auto-loaded); `hollow` / `outline` / `keep` / `replace` |
| `build_layers` | a whole structure in one call, drawn as ASCII layers + legend |
| `place_blocks` | individual blocks with states (`oak_stairs[facing=north]`, `lantern[hanging=true]`…) |
| `clone` | copy a build |
| `get_blocks` · `get_block` | read blocks: summary, ASCII layers, or a list |
| `render` | textured isometric (or top-down) PNG of an area — the AI's eyes |
| `player_info` | position, facing, dimension and the block under the crosshair |
| `read_chat` · `say` | in-game chat |
| `world_list` · `world_import` · `world_export` | move worlds between singleplayer, bundled maps and the server |
| `datapack_write` | write datapack files and `/reload` — minigame logic, live |
| `server_log` | server log |

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.

```python
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/`](mapgen/README.md).

## Troubleshooting

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

| Problem | Fix |
|---|---|
| "No Minecraft version found" / "libraries missing" | launch that version once from the launcher |
| "Java N not found" | same; or install Java N and set `JAVA` |
| custom `.minecraft` location | set `MC_DIR` |
| want a specific version | set `MC_VERSION`, e.g. `26.3` |
| port 25565 busy | change `server-port` in `mcserver/server.properties` |

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](https://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](https://aka.ms/MinecraftEULA)
  (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](LICENSE). Not an official Minecraft product; not approved by or associated with Mojang or Microsoft.