Content
# minecraft-schematic-lab
Build Minecraft schematics by talking to Claude. Describe what you want and it produces a WorldEdit
Sponge `.schem` with a live 3D preview in the browser. Everything runs locally — no account, no cloud.
## Setup
You need **Node 22+** and **Claude Code** (CLI or desktop app). Add the connector once — either way below
works for both the CLI and the desktop app, since they share the same config.
<details>
<summary><b>Add it with one command</b> (uses the <code>claude</code> CLI)</summary>
<br>
macOS / Linux:
```bash
claude mcp add --scope user minecraft-schematic-lab -- npx -y github:SimoneRecchia/minecraft-schematic-lab --mcp
```
Windows — `npx` needs a `cmd /c` wrapper:
```bat
claude mcp add --scope user minecraft-schematic-lab -- cmd /c npx -y github:SimoneRecchia/minecraft-schematic-lab --mcp
```
If `claude` isn't found, the desktop app doesn't ship the CLI — install it, open a new terminal, and run
the command again:
- **macOS** — `brew install --cask claude-code` (or `curl -fsSL https://claude.ai/install.sh | bash`)
- **Linux** — `curl -fsSL https://claude.ai/install.sh | bash`
- **Windows** — `winget install Anthropic.ClaudeCode` (or `irm https://claude.ai/install.ps1 | iex`)
</details>
<details>
<summary><b>Add it by hand</b> (edit the config file)</summary>
<br>
Add the block under `mcpServers` in your Claude config — `~/.claude.json` for Claude Code
(`%USERPROFILE%\.claude.json` on Windows), or `claude_desktop_config.json` for the Claude Desktop chat app.
macOS / Linux:
```json
{
"mcpServers": {
"minecraft-schematic-lab": {
"command": "npx",
"args": ["-y", "github:SimoneRecchia/minecraft-schematic-lab", "--mcp"]
}
}
}
```
Windows:
```json
{
"mcpServers": {
"minecraft-schematic-lab": {
"command": "cmd",
"args": ["/c", "npx", "-y", "github:SimoneRecchia/minecraft-schematic-lab", "--mcp"]
}
}
}
```
</details>
Restart Claude Code so it picks up the connector, then ask:
> build me a 50×40×80 fantasy castle
The first run pulls the tool through `npx`; the 3D preview then opens at <http://127.0.0.1:8765>.
## Using it
- **Change it** — "make the roof brick", "add two towers". The preview refreshes on its own.
- **Export** — the **Export .schem** button in the browser, or ask Claude (Sponge v2, or v3).
- **In Minecraft** — put the `.schem` in your world's `schematics` folder, then `//schem load <name>` and `//paste`.
- **Versions** — ask Claude to version a build in a folder (needs git).
- **Updates** — the connector follows `main`; pin a release with `#v0.1.0`, or clear a stale cache with `npm cache clean --force`.
## Platform support
| OS | CLI | Desktop app | Note |
| ------------------------------- | :-: | :---------: | -------------------------------- |
| macOS (Intel / Apple Silicon) | ✅ | ✅ | |
| Windows 10/11 (x64 / ARM64) | ✅ | ✅ | `npx` needs `cmd /c` (see Setup) |
| Linux (x64 / ARM64, incl. musl) | ✅ | — | no desktop app on Linux |
Node 22+ on every platform; 32-bit isn't supported.
## Develop
```bash
pnpm setup # install + build
pnpm dev # web (5173) + server (8765), hot reload
pnpm test # vitest
pnpm bundle # rebuild bundle/ for the npx connector (commit after server changes)
```
Architecture, MCP tools, the HTTP API and the BuildSpec format are documented in [`CLAUDE.md`](CLAUDE.md).
## License
MIT © 2026 SimoneRecchia
