minecraft-schematic-lab

A fully-local lab that lets Claude build Minecraft schematics for you. You describe what you want in plain language; Claude compiles it into a WorldEdit Sponge .schem, opens a browser preview so both of you can see it, and you iterate by chatting. Nothing leaves your machine — no database, no cloud, no account.

You (in Claude):  "build me a 50×40×80 fantasy castle"
        │
        ▼
   MCP server  ──compile──▶  BlockVolume  ──▶  Sponge .schem
        │                                         │
        └── opens ──▶  http://127.0.0.1:8765  (live 3D preview + Export)

Getting started — add one connector (no clone, nothing to build)

You don't clone or build anything. Add a single MCP connector that points at the public repo; npx fetches it, installs its dependencies, caches it, and runs it. The only prerequisite is Node 22+ (which gives you npx) and Claude Code.

Don't have Node yet? Install it once from https://nodejs.org (the official installer is the most trouble-free, especially for the desktop app).

Claude Code (CLI)

claude mcp add --scope user minecraft-schematic-lab -- npx -y github:SimoneRecchia/minecraft-schematic-lab --mcp

Claude Code (desktop app)

Open the MCP/connectors settings and add this server (or edit claude_desktop_config.json):

{
  "mcpServers": {
    "minecraft-schematic-lab": {
      "command": "npx",
      "args": ["-y", "github:SimoneRecchia/minecraft-schematic-lab", "--mcp"]
    }
  }
}

Then just ask

Restart Claude Code once so the connector loads, then tell it what you want, in any language:

"build me a 50×40×80 fantasy castle"

On the first request npx downloads and caches the tool (a few seconds), Claude builds your schematic, and the 3D preview opens by itself at http://127.0.0.1:8765. From then on:

• Build / change: "make the roof brick", "add two round towers" — the preview updates by itself.

• Export: click Export .schem in the browser (Sponge v2 by default, v3 optional), or ask Claude.

• Use it in Minecraft (WorldEdit / FAWE): put the .schem in your world's schematics folder, then //schem load <name> and //paste.

• Versioning (optional): ask Claude to "version this in folder …" — it sets up git for you (git must be installed).

Pinning / updating

The command above tracks the repo's main. To pin a stable version once releases are tagged, append the tag (this also sidesteps npx's git cache):

claude mcp add --scope user minecraft-schematic-lab -- npx -y "github:SimoneRecchia/minecraft-schematic-lab#v0.1.0" --mcp

If you ever get a stale build, refresh the cache once with npm cache clean --force.

Related MCP server: 3D MCP Server

Alternative: clone & let Claude Code set it up

Prefer to run from a local clone (e.g. to hack on it, or to let Claude Code install Node for you)? Clone the repo and open the folder as a project in Claude Code (CLI: cd in and run claude; desktop: add the folder as a project). Then ask it to build something — the first time, Claude Code reads CLAUDE.md, runs scripts/setup.sh (installs Node 22+ via nvm if missing, no admin password; enables pnpm; pnpm install && pnpm build; registers a local connector), builds your schematic, and opens the preview. After a one-time restart the MCP tools take over.

Fully manual: pnpm setup (= pnpm install && pnpm build), then claude mcp add --scope user minecraft-schematic-lab -- pnpm --dir <ABSOLUTE_PATH> mcp (CLI) or the equivalent mcpServers entry (desktop). If Node/pnpm are installed via nvm, the desktop app may not find them on its PATH — point the connector at scripts/mcp-launch.sh (the absolute-path wrapper scripts/setup.sh generates) instead of a bare pnpm.

The MCP process binds HTTP on 127.0.0.1:8765. Don't also run pnpm dev at the same time (port clash). To hack on the viewer with hot-reload use pnpm dev:web (port 5173).

MCP tools

HTTP API

BuildSpec & operations

A BuildSpec has id, name, minecraftVersion, size {x,y,z}, optional origin, a palette (friendly key → block id), and a list of operations:

box, hollow_box, wall_rect, gable_roof, cylinder, window_pattern, sphere, pyramid, ramp, replace, block_entity.

Block ids may be given directly (minecraft:stone) or via a palette key. Out-of-bounds writes are skipped and reported as warnings.

Schematic compatibility notes

• Sponge v2 is the default (broadest WorldEdit / FAWE support); v3 is available via ?version=3.

• BlockData is YZX-ordered unsigned LEB128 varints (stored as signed NBT bytes); the file is gzipped.

• DataVersion is an approximation derived from minecraftVersion (boundary-aware prefix match).

• Tile entities are emitted from block_entity operations (best-effort generic JSON → NBT).

• Not modeled: biomes and mob entities.

Security

• Binds loopback only (127.0.0.1).

• Git runs via argument arrays (never shell strings), uses repo-local config only (never --global), and never deletes. Project paths must live inside your home directory (symlink-safe).

Development

pnpm dev          # web (5173) + server (8765) with hot reload
pnpm typecheck
pnpm lint
pnpm test         # unit tests (vitest)
pnpm test:e2e     # Playwright (run: pnpm exec playwright install chromium)

Roadmap

Stairs/slabs orientation helpers, schematic import (read .schem back into a BuildSpec), more parametric shapes (arches, domes, spiral stairs), and a richer materials estimator.

License

MIT © 2026 SimoneRecchia