A Claude Code plugin that gives Claude agent
skills and an agent for driving a live Minecraft Java Edition world
through the minecraft-java-fabric-mcp-server
— a Fabric mod that embeds an MCP server inside Minecraft.
Built by the minecraft-builder agent: authored as a parametric voxel model,
render-checked against the design before placing, stamped into the world in a
single batch, then verified in-world — block-for-block.
And Ghasticlawd — the project's Ghast × Claude mascot — built the same way: voxelized, render-verified against the design, then placed and confirmed in-world.
And terrain, not just figures — this red-rock canyon, inspired by the national
parks of the American West, was shaped by the terrain-shape skill's terrain
toolkit: a parametric heightfield, hydraulically eroded, render-checked against
the design, then materialized into the world as block fills.
It does two things:
- Guided setup — skills and an agent that walk you, step by step, through standing up the whole stack: Minecraft Java with the Fabric loader, the MCP mod and its Fabric API dependency, the mod's configuration, and the connection to Claude.
- Building in the world — a
minecraft-builderagent that routes each request to one of fourbuild-*orchestrators, each of which sequences a set of model-tuned leaf skills — survey, research, plan, blueprint, build, verify, reflect — to design and construct elements in a live world.
This plugin is the Claude-facing piece of a two-repository system. The MCP server is embedded in the Fabric mod and runs inside Minecraft itself — there is no separate server process and no behavior pack.
| Repository | Role |
|---|---|
minecraft-java-fabric-mcp-server |
The Fabric mod. Embeds the MCP HTTP server and executes tool calls against the world on the server main thread. |
minecraft-java-fabric-claude-plugin (this repo) |
The Claude plugin — skills and agents that use the MCP tools. |
Claude (Code / Desktop)
│ MCP over Streamable HTTP (http://127.0.0.1:8765/mcp)
minecraft-java-fabric-mcp-server ← Fabric mod; embeds the MCP server
│ Minecraft server API + Fabric API (on the main thread)
the Minecraft world
The mod ships a separate jar for each supported Minecraft version, built against that version's Fabric API. A Minecraft or Fabric update can change the modding surface the mod depends on. Pin your Minecraft version, your Fabric API jar, and the mod jar to a matched, known-good set and upgrade them together. The mod's release notes list the supported Minecraft versions (v0.1.0 supports 1.21.11, 26.1.1, and 26.1.2). Treat the whole stack as experimental.
Get the MCP server mod from
Modrinth or
CurseForge
(or the GitHub Releases page) —
pick the jar matching your Minecraft version. The setup-mod skill walks you through it.
Add this repo as a plugin marketplace and install the plugin:
/plugin marketplace add chapmanjw/minecraft-java-fabric-claude-plugin
/plugin install minecraft-java@minecraft-java-claude
Then restart Claude Code. The skills appear under /minecraft-java:* and the
minecraft-mcp-setup and minecraft-builder agents become available for
delegation.
The four setup skills are meant to be run in order. Each one ends by handing off to the next. The default path is a single-player install on localhost (no token, no firewall changes); each skill also covers the dedicated Fabric server branch (LAN/remote, bearer-token auth).
| Skill | Phase | What it covers |
|---|---|---|
setup-fabric |
1 | Install Minecraft Java Edition and the Fabric loader — a single-player client or a headless dedicated server. |
setup-mod |
2 | Download the MCP mod jar and the matching Fabric API jar and install both into the mods/ folder. |
setup-server |
3 | Configure the mod's config.json, launch, and verify the embedded MCP server is listening (/healthz); capture the bearer token for remote setups. |
setup-connect |
4 | Register the MCP server with Claude and verify with a live tool call. |
To start a fresh setup, just ask Claude to set up Minecraft Java for MCP — the first skill triggers automatically — or invoke it explicitly:
/minecraft-java:setup-fabric
The build pipeline is organized in three tiers. The minecraft-builder agent is
Tier 1: it owns state and the quality gates and routes every request to exactly
one Tier-2 orchestrator. The four build-* orchestrators are domain playbooks
that sequence the Tier-3 leaf skills and thread one shared coherence context (one
survey, one terrain recipe, one palette, one biome plan, one integration pass) so
a build holds together. The leaves are single-purpose specialists, each running on
the model best suited to its work — heavy reasoning where it pays off, a small
model for mechanical execution. A leaf never hands off to a sibling; it returns its
result to the orchestrator, which sequences the next leaf. There is no trivial path:
every request runs the full gated spine, depth-scaled. Twenty-eight skills in all.
You can invoke any one directly, but the agent is the intended entry point.
The full list, tiers, and models live in
skills/TAXONOMY.md.
Tier 2 — build-* orchestrators (Opus, inline). Every request maps to one:
| Skill | Routes for |
|---|---|
build-natural-world |
terrain, landforms, biomes, water, natural scenery, named natural wonders, caves |
build-settlement |
villages, cities, districts, a building with grounds and context |
build-structure |
one named or standalone building, replica, statue/monument, player house |
build-systems |
redstone, farms, contraptions, transit lines, nether hubs, mechanisms |
Tier 3 — leaf specialists, grouped by prefix:
| Skill | Role | Model |
|---|---|---|
survey-site |
Investigates the live world — terrain, biomes, existing builds, surroundings. | Sonnet |
survey-research |
Researches real-world references, including geology and ecology, for faithful recreation. | Sonnet |
terrain-shape |
Designs naturalistic terrain as a recipe — mountains, water, biomes. | Sonnet |
terrain-landmark |
Composes recognizable real-world natural wonders from formation primitives. | Sonnet |
terrain-ecology |
Plants biome ecology and runs the scatter recipe. | Sonnet |
terrain-integrate |
Grounds a build into the world — apron erosion, seam blend (Gate B). | Sonnet |
terrain-cave |
Designs subterranean space — caves, caverns, ravines. | Sonnet |
design-house |
Designs a player's base of operations. | Opus |
design-village |
Designs settlements up to ~15 buildings, reusing standard building types. | Opus |
design-city |
Designs cities and districts (~16+) — urban fabric, zoning, streets, vernacular reuse. | Opus |
design-building |
Designs specific named buildings — real-world and fictional replicas, originals. | Opus |
design-monument |
Designs monuments and build-art — statues, creatures, sculpture, pixel art, logos. | Opus |
design-grounds |
Designs intentional outdoor space — gardens, parks, plazas, courtyards, hedge mazes. | Opus |
system-redstone |
Designs and verifies redstone and mechanical contraptions — Java-correct, with functional tests. | Opus |
system-transit |
Designs the connective network between builds — rail, roads, nether hubs, bridges, tunnels. | Opus |
exec-plan |
Captures requirements, interviews the user, produces a fully-resolved plan.toon. |
Opus |
exec-blueprint |
Turns the plan into named, reusable mcb:* structure templates in the world. |
Sonnet |
exec-worker |
Executes the plan step by step via the harness — mechanical, no redesign. | Haiku |
exec-inspect |
Verifies each build phase in-world and proposes course corrections (Gate C). | Sonnet |
exec-reflect |
Reviews the finished job and drafts process lessons for project memory. | Sonnet |
The terrain-*, design-*, system-*, and exec-* leaves carry reference/
libraries loaded on demand so the detail never bloats context until it is needed —
landforms and command budgets, rooms and styles and layouts, village mechanics,
urban zoning, architectural technique, redstone limits, contract checks, blueprint
rendering. The shared terrain core (reference/terrain/ — palettes, water,
weathering, formation primitives, non-negotiables) is promoted to the plugin root
and linked by every terrain leaf rather than copied.
For representational and parametric builds (vehicles, creatures, statues),
design-monument runs a render-verify loop backed by a bundled Python voxel
toolkit (tools/voxel/, numpy + Pillow): author the form as a parametric model,
render three orthogonal views to PNG and check the silhouette before placing a
block, stamp the whole thing into the world in one block_fill_batch, then confirm
with an in-world block_render_region. See tools/README.md.
The agent can't see the world, and a wrong silhouette can't be detailed away — so
the cheap iteration happens on a render first. (The bean above was built exactly
this way.)
Terrain works the same way through a separate toolkit. terrain-shape and the
other terrain leaves author land as a recipe — a composable sampler graph —
verify it offline (Gate A: ziggurat, seam, and relief checks), and materialize it
with block_fill_columns in one server call rather than a voxel grid. The terrain
toolkit (tools/terrain/) adds scipy to the numpy + Pillow base, and uses
opensimplex when present (falling back to Perlin noise otherwise). The build
harness (tools/builder/) is stdlib-only. Install all the Python deps once with
python -m pip install -r tools/requirements.txt.
minecraft-mcp-setup — orchestrates the complete setup end to end. It runs
all four phases in one continuous session: checks prerequisites up front, works
each phase interactively, verifies every phase's checklist before advancing,
and carries forward the values later phases depend on (paths, ports, token,
host).
minecraft-builder — designs and constructs elements in a live world. It
health-checks the MCP connection (and points you at minecraft-mcp-setup if
the world isn't reachable), recovers existing project state from the world, then
routes the request to one of the four build-* orchestrators, which sequences the
leaf skills through one gated spine: survey → research → plan → shape → ecology →
blueprint → build → integrate → inspect → register → reflect. Delegate to it for
any build — e.g. "Build a lakeside village near the nearest player."
Use the individual /minecraft-java:* skills directly if you'd rather drive
one step yourself.
The builder keeps persistent state in the Minecraft world, not in your workspace — a project folder is useful only while you're working in it, but the world travels everywhere:
- Blueprints are saved as named structure templates (
mcb:<project>_<element>) via thestructure_*tools, so build elements can be placed, copied, and iterated later. - A registry — vanilla command storage at
mcbuilder:registry, holding a TOON document (read/written with thedata_storage_*tools) — records every project and build (element, structure, coordinates, dimension, status, revision). Any future session reads it back and can pick up where the last left off.
Local files under .minecraft-builder/<project>/ (requirements, survey, plan)
are treated as throwaway scratch — Markdown for prose, TOON for structured
data. The exec-reflect skill records only process lessons in project memory,
never build data.
This plugin does not auto-register an MCP server, because the endpoint and
posture are per-user (your own host, port, and — for remote setups — a bearer
token). The setup-connect skill registers it for you.
For a single-player install the mod listens on http://127.0.0.1:8765/mcp
with no authentication — just the URL is needed. For a dedicated/remote
server the mod generates a bearer token on first boot; pass it via an
environment variable so it stays out of version control.
.mcp.json.example in this repo is a reference template
showing both the no-auth localhost form and the token-via-env pattern.
The mod actually exposes two servers from one jar: minecraft-java (the
world tools, port 8765) and an optional minecraft-java-client (inspection —
view_capture returns the player's real first-person frame, plus sense_* /
client_status, port 8766) that runs inside a real rendered client so Claude can
SEE the world as a player does. Connect the world server always; add the
inspection server when a client is running (single-player serves both from one
process). setup-connect covers the server-only, client-only, and server+client
patterns, and exec-inspect uses the real-client frame for in-game verification
when it's connected.
See CONTRIBUTING.md for conventions and how to validate changes, CHANGELOG.md for release history, and SECURITY.md to report a vulnerability.
MIT — see LICENSE.