blockwright
An MCP server that lets an AI assistant build and manage real structures on a live Minecraft Java server over RCON, with previews, world reads, and undo.
Build from ASCII layers, geometric shapes, or
.schem/.nbtschematic files; fill boxes and paste schematics with rotation/mirroring.Terraform terrain: blend a building pad into the hillside, smooth rough ground, raise hills, and scatter plants/boulders on real ground.
Preview builds as ASCII slices and a self-contained 3D HTML viewer, optionally in place on real terrain; render the world or schematics as PNG images from multiple angles.
Read the world: heightmaps for site scouting, single-block reads, block-count region reads, and saving world regions to schematic files.
Analyze terrain numerically: walk paths for steps/drops/headroom/obstacles, profile ground grades and cross-sections, and map slope steepness and walkability.
Undo writes safely: every write is snapshotted first; list and restore snapshots with
undo.Inspect and write schematic files without touching the server.
Run raw server console commands (e.g. time, weather, tp) while administrative commands are refused unless explicitly enabled.
Get server info and online player positions to choose build sites near players.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@blockwright Build a 5x5 oak wood house at (100, 64, 200) and preview it before placing."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
blockwright
An MCP server that lets an AI assistant build real structures on a live Minecraft Java server. No client mod, no bot account: it talks to the server console over RCON, previews every build first, reads the world back from the region files, and snapshots before each write so it can undo.
Build from ASCII layers, geometric shapes, or
.schem/.nbtschematic filesTerraform: ramp a building pad into the surrounding hillside with a solved, seamless, walkable slope, smooth rough ground, or raise a hill — then scatter plants and boulders that can only land on real ground
Preview as ASCII slices for the assistant and a self-contained 3D HTML viewer for you, optionally shown in place on the real terrain
Read the world: heightmaps for scouting a site, block reads to verify a build, save any region to a schematic
Check the ground by the numbers: walk a path block by block for steps, drops, headroom and obstacles; profile a line for its grade and cross-section; map the steepness and cliffs of an area
Undo: every write is snapshotted to disk first and restored with one call
Works on vanilla, Paper, Spigot, Fabric servers with RCON enabled; tested on Paper 26.2
Quick start
Requirements: Node ≥ 20 and a server with enable-rcon=true in server.properties.
Claude Code .mcp.json (project) or ~/.claude.json:
{
"mcpServers": {
"blockwright": {
"command": "npx",
"args": ["-y", "github:ThatHunky/blockwright"],
"env": {
"BLOCKWRIGHT_SERVER_DIR": "/path/to/your/server"
}
}
}
}BLOCKWRIGHT_SERVER_DIR is the folder containing server.properties. From it blockwright reads the RCON port and password, the level name, the Minecraft version, and the region files it needs for reads and undo. If blockwright runs on another machine, set BLOCKWRIGHT_RCON_HOST/PORT/PASSWORD instead; building works, but reads and undo need the server folder (or the plugin, coming in a later release).
An example config for the Matsuri server is in .mcp.example.json — copy it to .mcp.json (gitignored, since it can carry a real server path) and adjust the paths.
Then ask: "Scout a flat spot near me and build a small stone cottage. Preview first."
Related MCP server: MCP Minecraft Remote
Configuration
Variable | Default | Purpose |
| — | Server folder. Enables reading |
|
| |
| from | |
| from | Required one way or the other |
|
| Overworld folder name |
| — |
|
|
| Blocks per |
|
| Upper bound on how many voxels |
|
| Above this many commands, a build is placed as structure templates instead |
|
| Template tile size |
|
| Where relative schematic paths resolve |
|
| Where preview HTML and |
| from | Override when there is no server folder |
| unset | Set to |
|
| Reads skip |
| — | Shown in |
Tools
Tool | What it does |
| Version, players, whether reads/snapshots work, effective config |
| Names, worlds, positions, look direction, gamemode |
| Surface heights and blocks for an x/z rectangle: find a site and the y to build at |
| ASCII slices plus a 3D HTML viewer of a build spec, shape, or schematic, optionally with the surrounding terrain |
| Draw the live world (or a schematic) as PNGs from four isometric corners, a plan view or a straight-on elevation, returned inline |
| Walk a polyline block by block: exact standing heights, every step over 0.6, drop over 3, blocked headroom, water and obstacle with coordinates |
| Ground elevation along a line with grades, trees and water, an optional cross-section, and an ASCII elevation chart |
| Steepness map of an x/z box as characters, the cliffs in it, and how much of it is walkable |
| Place a structure written as ASCII layers with a character palette |
| Sphere, dome, cylinder, cone, pyramid, line, circle |
| Box fill: replace (with filter), keep, destroy, hollow, outline |
| Shape natural ground: |
| Plants and boulders on solid ground with air above, by density, palette and seed |
| Paste a |
| Inspect a file, write one from a spec, or copy a world region into one |
| Verify what is in the world |
| Restore the snapshot taken before a write |
| Raw console command with an admin denylist |
Every write tool accepts dry_run, snapshot, label, world and allow_unknown_blocks.
How it works
Voxels compile to the fewest
fill/setblockcommands (greedy box merging), split under the 32768-block limit, supports before torches and doors, chunks force-loaded for the duration.Big pastes are written as vanilla structure files into
<world>/generated/blockwright/structure/and placed withplace template, which needs no reload and no physics pass.Reads run
save-all flushand parse the Anvil region files directly (26.xdimensions/layout and the classic layout). Heightmaps come straight from the chunk data.Snapshots are the read box written as structure files, restored with
place template, so they survive restarts. The newest 50 are kept.
Terraforming
terraform exists because levelling a site with fill leaves a cut cube in the landscape, and hand-rolled slopes come out as terraces or concentric rings. It works on the height field instead:
Read the box and find the real ground surface per column — the highest solid block, ignoring leaves, logs, snow and water, so one oak does not put the "surface" twelve blocks up. Without world reads it falls back to a console probe (
execute if block … air, binary-searched per column), which is slower, capped, and cannot snapshot.Freeze what must not move: the box border (so the result meets real terrain with no seam), the pad given by
keep_from/keep_to, anything inprotect, and any ungenerated column.Solve the interior as a harmonic field (multigrid Gauss-Seidel) with those frozen values as boundary conditions. A harmonic function has no interior maximum or minimum, so the ramp between pad and terrain can only descend — no terraces, no rings.
Add 4 octaves of value-noise fBm at a 32-block base wavelength (the octave counts and wavelengths vanilla uses for its own surface noise), with its amplitude faded to zero at both the pad edge and the border, seeded so the same call always gives the same ground.
Box-blur, round to whole blocks, and clamp the height difference between neighbouring columns to
max_step(default 1) so the result is walkable. When the pad height and the border terrain simply cannot be joined that gently, it says so instead of hiding a cliff.Apply per column: air above the new surface,
top_block,soil_depthblocks of soil, then stone only where there is nothing already — existing stone, ores and caves below the fill are never replaced. Columns that are already at their target emit nothing at all, which is what leaves the border and its trees untouched.
Everything goes through the normal voxel pipeline, so dry_run, snapshots and undo work as they do for build.
scatter reads the same column view and places only at ground + 1 with air above it: two-block plants get both halves, and a boulder (radius 1-3) grows each of its sub-columns from that column's own ground, so nothing it emits can be unsupported.
Looking at what you built
read_region counts blocks and get_heightmap gives surface heights, but neither shows whether
a build looks right. render reads a box of the world and returns real PNG images, inline, so
an assistant can see its own work:
render from: [-978, 55, 448] to: [-960, 76, 498]
views: ["iso_se", "iso_nw"]views—iso_ne/iso_nw/iso_se/iso_sw(the four isometric corners),top(a plan, north up) andnorth/south/east/west(straight-on elevations). Up to four per call.Blocks are drawn with the shape they actually have: a fence is a post, a slab is half a cell, a lantern is a small lamp, a plant is a tuft. Drawing them all as cubes is what makes a bridge with a gappy deck look like a solid slab — and hides exactly the mistake the picture exists to catch.
hidetakes block names or globs (["*_leaves"],["water"]) so a structure can be seen through a forest or a lake.cutaway_yignores everything above a height, which lifts the roof off an interior.scaleandmax_pixelstrade detail against size; images over ~900 KB are written to disk and their paths returned instead of being inlined.
One corner is not enough. A top-down view hides every vertical mistake there is, so look from at least two opposite corners before calling anything finished.
Checking the ground by the numbers
A picture shows whether a build looks right; it does not show a 1-block lip on a path, a stair
climbed into its back, or leaves at head height. walk, profile and slope read the same
region files and answer in text an assistant can check line by line:
walk path: [[-1127, 128, 289], [-1119, 128, 286], [-1119, 127, 272]]walkfills the polyline in as a 4-connected grid line and finds the floor of every cell — near the given y (±8), or the highest walkable surface for[x, z]points. Standing height is the block's collision top: a bottom slab is +0.5,dirt_pathand farmland 15/16, a carpet 1/16, a snow layer one layer less than it looks; flowers, grass, torches and signs are walked through; leaves, fences and walls are obstacles, never floors. A bottom stair entered from anywhere but its back counts as two half steps. Problems:step_up(overmax_step, default 0.6),fall(over 3),no_floor,water,headroom(default 2 clear blocks),obstacle,ungenerated. Flat stretches are run-length collapsed.profilelists ground height along a line — plants, leaves and logs ignored, trees and water reported separately — with total rise and fall, the steepest change over 1, 3 and 10 cells, an ASCII elevation chart, and withwidtha cross-section per cell that shows a road sunk in a trench.slopedraws each column's largest step to its neighbours (.level,:a walkable half step,1–9blocks,#10+,~water), lists connected cliffs of 1.5+ blocks with their extent and height, and says how much of the area can be walked without jumping.
All three read one chunk at a time over only the y range they need, into a small bounded cache, so a long diagonal path costs a few chunk reads rather than its bounding box.
Safety
Nothing is written without a compiled command list;
dry_runshows it.BLOCKWRIGHT_BOUNDSfences the assistant into an area.Snapshots are on by default whenever reads are available.
Running two blockwright processes against the same server directory at once can lose a snapshot record (each process only serializes writes to
snapshots.jsonagainst itself, not against the other). Don't rely on undo in that configuration — run one blockwright process per server directory.run_commandrefuses administrative commands unless you opt in.The RCON password never appears in tool output.
Development
npm install
npm test # vitest, no server needed
npm run integration # against a real server, see scripts/integration.tsDesign spec: docs/superpowers/specs/2026-09-08-blockwright-design.md.
License
MIT
Available Tools
16 toolsbuildBuild from ASCII layersA
Place a structure described as layers of characters. palette maps one character to a block state; rows run north→south (z), characters west→east (x); y is height above origin. Space leaves the world alone. Extra single blocks go in "blocks". Rotation keeps the min corner at origin. Run with dry_run=true first, and preview before that.
Inputs: origin (required), label, world, blocks, +7 more.
fillFill a boxA
Fill a box with one block. Modes: replace (optionally only blocks matching replace_filter), keep (only air), destroy (drop items), hollow (walls + air inside), outline (walls only, interior untouched). Splits over the 32768-block command limit automatically.
Inputs: to (required), from (required), block (required), mode, +6 more.
get_blockRead one blockC
The block state at a position.
Inputs: pos (required), world.
get_heightmapSurface heightmapA
Surface y and surface block for an x/z rectangle, as a sampled grid (rows = z north→south, columns = x west→east). The site-scouting tool: find flat ground and the y to build at (surface y + 1).
Inputs: to (required), from (required), world, sample.
get_playersOnline playersA
Names, worlds, block positions, look direction and gamemode of online players. Use to pick a build site near someone.
Inputs: no named parameters.
list_snapshotsList snapshotsA
Snapshots taken before writes, newest first, with ids for undo.
Inputs: no named parameters.
paste_schematicPaste a schematic fileA
Paste a Sponge .schem or vanilla structure .nbt. By default origin is where the schematic's min corner lands; use_offset=true adds the file's stored offset like WorldEdit //paste. ignore_air skips air so the surroundings survive.
Inputs: path (required), origin (required), label, world, +7 more.
place_shapePlace a geometric shapeC
Sphere, dome, cylinder, cone, pyramid, line or circle, filled or hollow. Radius r gives a diameter of 2r+1.
Inputs: block (required), shape (required), to, base, +14 more.
previewPreview a build before placing itB
Render a build spec, a shape, or a schematic as ASCII layer slices (returned) and as a self-contained 3D HTML viewer (path returned; send that file to the user). Set context>0 to include the surrounding world blocks so the design is shown in place. Nothing is changed in the world.
Inputs: build, shape, title, world, +3 more.
read_regionRead blocks from the worldA
Block counts for a box, plus ASCII layer slices when the box is small (≤4096 blocks) or full=true. Use after building to verify the result.
Inputs: to (required), from (required), full, world, +1 more.
run_commandRun console commandA
Run a raw server console command and return its output. Administrative commands (stop, op, ban, whitelist, kick, reload…) are refused unless BLOCKWRIGHT_ALLOW_ADMIN=1. Prefer the build tools; use this for things like time, weather, tp, give, say.
Inputs: command (required).
save_schematicSave a world region to a schematic fileB
Copy a box from the world into a .schem (Sponge v3) or .nbt (structure) file, block entities included.
Inputs: to (required), from (required), path (required), world, +1 more.
schematic_infoInspect a schematic fileB
Format, size, offset, DataVersion, block counts and block-entity count of a .schem/.nbt file.
Inputs: path (required).
schematic_writeWrite a schematic fileA
Save a build spec or a shape as a .schem (Sponge v3) or .nbt (vanilla structure) file without touching any server. Relative paths go to the schematic dir.
Inputs: path (required), build, shape, format.
server_infoServer infoB
Minecraft version, player count, whether world reads/snapshots are available, and the effective blockwright configuration.
Inputs: no named parameters.
undoUndo recent writesA
Restore the newest snapshot(s) taken before writes (or a specific id from list_snapshots). Each restored snapshot is removed from the list.
Inputs: id, steps.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools map to a distinct workflow step: reading world state, previewing designs, writing blocks, managing schematics, and undoing. A few could be confused at a glance—save_schematic vs schematic_write and preview vs read_region—but the descriptions clearly separate them.
There is a recognizable pattern with get_* for queries and verb_noun for many actions, but bare verbs like fill, build, undo, and preview plus the reversed schematic_info and schematic_write break the pattern. The names are still readable and meaningful, just not fully consistent.
Sixteen tools is somewhat high, but each one earns its place across querying, editing, previewing, schematics, and undo. There is no obvious redundancy, and the count feels appropriate for a Minecraft world-building server.
The toolset covers the core build-verify-undo-schematic lifecycle well: inspect terrain, build with multiple methods, preview designs, read results, save/paste schematics, and undo writes. Minor gaps like no schematic file listing or paste rotation are workarounds rather than dead ends.
Related MCP Connectors
Minecraft builds and skins made by your AI agent, live in your browser tab. Export .schem.
Manage NodePal Minecraft servers, worlds, mods, backups and console from AI agents.
Generate AI video, images and audio, and browse your history, from any MCP client.
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI interactions with a running Minecraft server inside a Docker container using RCON, allowing models to programmatically create Minecraft builds and manage the server.10-
- AlicenseCqualityDmaintenanceAllows AI assistants to connect to and control Minecraft players on remote servers, enabling navigation, building, mining, inventory management, entity interaction, and chat communication through natural language commands.2711 npm13MIT
- FlicenseNot gradedqualityDmaintenanceEnables control of a Minecraft server through RCON commands via natural language, including game commands, chat-based AI interactions, and server management capabilities.6-
- AlicenseAqualityCmaintenanceLets an AI assistant control a live Minecraft server over RCON: list players, broadcast chat, teleport, give items, change weather/time, kick, or run any raw vanilla/plugin command.8MIT