{"id":50907187,"url":"https://github.com/chapmanjw/minecraft-java-fabric-claude-plugin","last_synced_at":"2026-06-16T06:03:57.538Z","repository":{"id":359266880,"uuid":"1245154482","full_name":"chapmanjw/minecraft-java-fabric-claude-plugin","owner":"chapmanjw","description":"Claude Plugin with Skills and Agents for the MCP Server Mod for Minecraft Java Edition and the FabricMC Fabric API","archived":false,"fork":false,"pushed_at":"2026-06-08T06:55:25.000Z","size":2922,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T07:24:52.918Z","etag":null,"topics":["claude","mcp","mcp-server","minecraft","minecraft-java","minecraft-mod"],"latest_commit_sha":null,"homepage":"https://github.com/chapmanjw/minecraft-java-fabric-mcp-server","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chapmanjw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"chapmanjw"}},"created_at":"2026-05-21T00:57:29.000Z","updated_at":"2026-06-08T06:55:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chapmanjw/minecraft-java-fabric-claude-plugin","commit_stats":null,"previous_names":["chapmanjw/minecraft-java-fabric-claude-plugin"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/chapmanjw/minecraft-java-fabric-claude-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chapmanjw%2Fminecraft-java-fabric-claude-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chapmanjw%2Fminecraft-java-fabric-claude-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chapmanjw%2Fminecraft-java-fabric-claude-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chapmanjw%2Fminecraft-java-fabric-claude-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chapmanjw","download_url":"https://codeload.github.com/chapmanjw/minecraft-java-fabric-claude-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chapmanjw%2Fminecraft-java-fabric-claude-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34393302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","mcp","mcp-server","minecraft","minecraft-java","minecraft-mod"],"created_at":"2026-06-16T06:03:56.258Z","updated_at":"2026-06-16T06:03:57.533Z","avatar_url":"https://github.com/chapmanjw.png","language":"Python","funding_links":["https://github.com/sponsors/chapmanjw"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/logo.png\" width=\"200\" alt=\"Minecraft Java Fabric MCP — Claude plugin logo\"\u003e\n\u003c/p\u003e\n\n# Minecraft Java — Claude Plugin\n\nA [Claude Code](https://code.claude.com) plugin that gives Claude **agent\nskills** and an **agent** for driving a live Minecraft Java Edition world\nthrough the [`minecraft-java-fabric-mcp-server`](https://github.com/chapmanjw/minecraft-java-fabric-mcp-server)\n— a Fabric mod that embeds an MCP server inside Minecraft.\n\n![A voxel mascot standing on a superflat world, built by the minecraft-builder agent](docs/images/bean.png)\n\n*Built by the `minecraft-builder` agent: authored as a parametric voxel model,\nrender-checked against the design before placing, stamped into the world in a\nsingle batch, then verified in-world — block-for-block.*\n\n![Ghasticlawd, a voxel Ghast-and-Claude mascot, built in a live world](docs/images/ghasticlawd.png)\n\n*And **Ghasticlawd** — the project's Ghast × Claude mascot — built the same way:\nvoxelized, render-verified against the design, then placed and confirmed in-world.*\n\n![A layered red-rock canyon inspired by the national parks of the American West, terraformed in a live world](docs/images/canyon.png)\n\n*And terrain, not just figures — this red-rock canyon, inspired by the national\nparks of the American West, was shaped by the `terrain-shape` skill's terrain\ntoolkit: a parametric heightfield, hydraulically eroded, render-checked against\nthe design, then materialized into the world as block fills.*\n\nIt does two things:\n\n1. **Guided setup** — skills and an agent that walk you, step by step, through\n   standing up the whole stack: Minecraft Java with the Fabric loader, the MCP\n   mod and its Fabric API dependency, the mod's configuration, and the\n   connection to Claude.\n2. **Building in the world** — a `minecraft-builder` agent that routes each\n   request to one of four `build-*` orchestrators, each of which sequences a set\n   of model-tuned leaf skills — survey, research, plan, blueprint, build, verify,\n   reflect — to design and construct elements in a live world.\n\n## The stack\n\nThis plugin is the Claude-facing piece of a two-repository system. The MCP\nserver is **embedded in the Fabric mod** and runs inside Minecraft itself —\nthere is no separate server process and no behavior pack.\n\n| Repository | Role |\n| ---------- | ---- |\n| [`minecraft-java-fabric-mcp-server`](https://github.com/chapmanjw/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. |\n| **`minecraft-java-fabric-claude-plugin`** (this repo) | The Claude plugin — skills and agents that use the MCP tools. |\n\n```\nClaude (Code / Desktop)\n   │  MCP over Streamable HTTP  (http://127.0.0.1:8765/mcp)\nminecraft-java-fabric-mcp-server   ← Fabric mod; embeds the MCP server\n   │  Minecraft server API + Fabric API  (on the main thread)\nthe Minecraft world\n```\n\n## ⚠️ Pin your versions\n\nThe mod ships a separate jar for each supported Minecraft version, built against\nthat version's Fabric API. A Minecraft or Fabric update can change the modding\nsurface the mod depends on. Pin your Minecraft version, your Fabric API jar, and\nthe mod jar to a matched, known-good set and upgrade them together. The mod's\nrelease notes list the supported Minecraft versions (v0.1.0 supports **1.21.11,\n26.1.1, and 26.1.2**). Treat the whole stack as experimental.\n\nGet the MCP server mod from\n[**Modrinth**](https://modrinth.com/mod/fabric-api-mcp-server) or\n[**CurseForge**](https://www.curseforge.com/minecraft/mc-mods/fabric-api-mcp-server)\n(or the [GitHub Releases page](https://github.com/chapmanjw/minecraft-java-fabric-mcp-server/releases)) —\npick the jar matching your Minecraft version. The `setup-mod` skill walks you through it.\n\n## Install\n\nAdd this repo as a plugin marketplace and install the plugin:\n\n```\n/plugin marketplace add chapmanjw/minecraft-java-fabric-claude-plugin\n/plugin install minecraft-java@minecraft-java-claude\n```\n\nThen restart Claude Code. The skills appear under `/minecraft-java:*` and the\n`minecraft-mcp-setup` and `minecraft-builder` agents become available for\ndelegation.\n\n## Setup skills\n\nThe four setup skills are meant to be run **in order**. Each one ends by\nhanding off to the next. The default path is a **single-player** install on\nlocalhost (no token, no firewall changes); each skill also covers the\n**dedicated Fabric server** branch (LAN/remote, bearer-token auth).\n\n| Skill | Phase | What it covers |\n| ----- | ----- | -------------- |\n| `setup-fabric` | 1 | Install Minecraft Java Edition and the Fabric loader — a single-player client or a headless dedicated server. |\n| `setup-mod` | 2 | Download the MCP mod jar and the matching Fabric API jar and install both into the `mods/` folder. |\n| `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. |\n| `setup-connect` | 4 | Register the MCP server with Claude and verify with a live tool call. |\n\nTo start a fresh setup, just ask Claude to set up Minecraft Java for MCP — the\nfirst skill triggers automatically — or invoke it explicitly:\n\n```\n/minecraft-java:setup-fabric\n```\n\n## Builder skills\n\nThe build pipeline is organized in three tiers. The `minecraft-builder` agent is\nTier 1: it owns state and the quality gates and routes every request to exactly\none Tier-2 orchestrator. The four `build-*` orchestrators are domain playbooks\nthat sequence the Tier-3 leaf skills and thread one shared coherence context (one\nsurvey, one terrain recipe, one palette, one biome plan, one integration pass) so\na build holds together. The leaves are single-purpose specialists, each running on\nthe model best suited to its work — heavy reasoning where it pays off, a small\nmodel for mechanical execution. A leaf never hands off to a sibling; it returns its\nresult to the orchestrator, which sequences the next leaf. There is no trivial path:\nevery request runs the full gated spine, depth-scaled. Twenty-eight skills in all.\nYou can invoke any one directly, but the agent is the intended entry point.\n\nThe full list, tiers, and models live in\n[`skills/TAXONOMY.md`](skills/TAXONOMY.md).\n\n**Tier 2 — `build-*` orchestrators** (Opus, inline). Every request maps to one:\n\n| Skill | Routes for |\n| ----- | ---------- |\n| `build-natural-world` | terrain, landforms, biomes, water, natural scenery, named natural wonders, caves |\n| `build-settlement` | villages, cities, districts, a building with grounds and context |\n| `build-structure` | one named or standalone building, replica, statue/monument, player house |\n| `build-systems` | redstone, farms, contraptions, transit lines, nether hubs, mechanisms |\n\n**Tier 3 — leaf specialists**, grouped by prefix:\n\n| Skill | Role | Model |\n| ----- | ---- | ----- |\n| `survey-site` | Investigates the live world — terrain, biomes, existing builds, surroundings. | Sonnet |\n| `survey-research` | Researches real-world references, including geology and ecology, for faithful recreation. | Sonnet |\n| `terrain-shape` | Designs naturalistic terrain as a recipe — mountains, water, biomes. | Sonnet |\n| `terrain-landmark` | Composes recognizable real-world natural wonders from formation primitives. | Sonnet |\n| `terrain-ecology` | Plants biome ecology and runs the scatter recipe. | Sonnet |\n| `terrain-integrate` | Grounds a build into the world — apron erosion, seam blend (Gate B). | Sonnet |\n| `terrain-cave` | Designs subterranean space — caves, caverns, ravines. | Sonnet |\n| `design-house` | Designs a player's base of operations. | Opus |\n| `design-village` | Designs settlements up to ~15 buildings, reusing standard building types. | Opus |\n| `design-city` | Designs cities and districts (~16+) — urban fabric, zoning, streets, vernacular reuse. | Opus |\n| `design-building` | Designs specific named buildings — real-world and fictional replicas, originals. | Opus |\n| `design-monument` | Designs monuments and build-art — statues, creatures, sculpture, pixel art, logos. | Opus |\n| `design-grounds` | Designs intentional outdoor space — gardens, parks, plazas, courtyards, hedge mazes. | Opus |\n| `system-redstone` | Designs and verifies redstone and mechanical contraptions — Java-correct, with functional tests. | Opus |\n| `system-transit` | Designs the connective network between builds — rail, roads, nether hubs, bridges, tunnels. | Opus |\n| `exec-plan` | Captures requirements, interviews the user, produces a fully-resolved `plan.toon`. | Opus |\n| `exec-blueprint` | Turns the plan into named, reusable `mcb:*` structure templates in the world. | Sonnet |\n| `exec-worker` | Executes the plan step by step via the harness — mechanical, no redesign. | Haiku |\n| `exec-inspect` | Verifies each build phase in-world and proposes course corrections (Gate C). | Sonnet |\n| `exec-reflect` | Reviews the finished job and drafts process lessons for project memory. | Sonnet |\n\nThe `terrain-*`, `design-*`, `system-*`, and `exec-*` leaves carry `reference/`\nlibraries loaded on demand so the detail never bloats context until it is needed —\nlandforms and command budgets, rooms and styles and layouts, village mechanics,\nurban zoning, architectural technique, redstone limits, contract checks, blueprint\nrendering. The shared terrain core (`reference/terrain/` — palettes, water,\nweathering, formation primitives, non-negotiables) is promoted to the plugin root\nand linked by every terrain leaf rather than copied.\n\nFor representational and parametric builds (vehicles, creatures, statues),\n`design-monument` runs a **render-verify loop** backed by a bundled Python voxel\ntoolkit (`tools/voxel/`, numpy + Pillow): author the form as a parametric model,\nrender three orthogonal views to PNG and check the silhouette *before* placing a\nblock, stamp the whole thing into the world in one `block_fill_batch`, then confirm\nwith an in-world `block_render_region`. See [`tools/README.md`](tools/README.md).\nThe agent can't see the world, and a wrong silhouette can't be detailed away — so\nthe cheap iteration happens on a render first. (The bean above was built exactly\nthis way.)\n\nTerrain works the same way through a separate toolkit. `terrain-shape` and the\nother terrain leaves author land as a **recipe** — a composable sampler graph —\nverify it offline (Gate A: ziggurat, seam, and relief checks), and materialize it\nwith `block_fill_columns` in one server call rather than a voxel grid. The terrain\ntoolkit (`tools/terrain/`) adds **scipy** to the numpy + Pillow base, and uses\n**opensimplex** when present (falling back to Perlin noise otherwise). The build\nharness (`tools/builder/`) is stdlib-only. Install all the Python deps once with\n`python -m pip install -r tools/requirements.txt`.\n\n## Agents\n\n**`minecraft-mcp-setup`** — orchestrates the complete setup end to end. It runs\nall four phases in one continuous session: checks prerequisites up front, works\neach phase interactively, verifies every phase's checklist before advancing,\nand carries forward the values later phases depend on (paths, ports, token,\nhost).\n\n**`minecraft-builder`** — designs and constructs elements in a live world. It\nhealth-checks the MCP connection (and points you at `minecraft-mcp-setup` if\nthe world isn't reachable), recovers existing project state from the world, then\nroutes the request to one of the four `build-*` orchestrators, which sequences the\nleaf skills through one gated spine: survey → research → plan → shape → ecology →\nblueprint → build → integrate → inspect → register → reflect. Delegate to it for\nany build — e.g. *\"Build a lakeside village near the nearest player.\"*\n\nUse the individual `/minecraft-java:*` skills directly if you'd rather drive\none step yourself.\n\n## State model\n\nThe builder keeps **persistent state in the Minecraft world**, not in your\nworkspace — a project folder is useful only while you're working in it, but the\nworld travels everywhere:\n\n- **Blueprints** are saved as named structure templates (`mcb:\u003cproject\u003e_\u003celement\u003e`)\n  via the `structure_*` tools, so build elements can be placed, copied, and\n  iterated later.\n- A **registry** — vanilla command storage at `mcbuilder:registry`, holding a\n  [TOON](https://toonformat.dev/) document (read/written with the\n  `data_storage_*` tools) — records every project and build (element, structure,\n  coordinates, dimension, status, revision). Any future session reads it back\n  and can pick up where the last left off.\n\nLocal files under `.minecraft-builder/\u003cproject\u003e/` (requirements, survey, plan)\nare treated as throwaway scratch — Markdown for prose, TOON for structured\ndata. The `exec-reflect` skill records only *process lessons* in project memory,\nnever build data.\n\n## MCP connection\n\nThis plugin does **not** auto-register an MCP server, because the endpoint and\nposture are per-user (your own host, port, and — for remote setups — a bearer\ntoken). The `setup-connect` skill registers it for you.\n\nFor a **single-player** install the mod listens on `http://127.0.0.1:8765/mcp`\nwith no authentication — just the URL is needed. For a **dedicated/remote**\nserver the mod generates a bearer token on first boot; pass it via an\nenvironment variable so it stays out of version control.\n[`.mcp.json.example`](.mcp.json.example) in this repo is a reference template\nshowing both the no-auth localhost form and the token-via-env pattern.\n\nThe mod actually exposes **two** servers from one jar: `minecraft-java` (the\nworld tools, port 8765) and an optional `minecraft-java-client` (inspection —\n`view_capture` returns the player's real first-person frame, plus `sense_*` /\n`client_status`, port 8766) that runs inside a real rendered client so Claude can\nSEE the world as a player does. Connect the world server always; add the\ninspection server when a client is running (single-player serves both from one\nprocess). `setup-connect` covers the server-only, client-only, and server+client\npatterns, and `exec-inspect` uses the real-client frame for in-game verification\nwhen it's connected.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for conventions and how to validate\nchanges, [CHANGELOG.md](CHANGELOG.md) for release history, and\n[SECURITY.md](SECURITY.md) to report a vulnerability.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchapmanjw%2Fminecraft-java-fabric-claude-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchapmanjw%2Fminecraft-java-fabric-claude-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchapmanjw%2Fminecraft-java-fabric-claude-plugin/lists"}