Minecraft Java Fabric Mcp Server

Minecraft Java MCP Server (Fabric)

> Install the mod from Modrinth or > CurseForge. Pick the jar > that matches your Minecraft version, drop it in mods/ alongside Fabric API, and launch. Full > walkthrough in [Quick start](#quick-start-single-player-default-config) below.

A Model Context Protocol (MCP) server that runs inside Minecraft Java Edition as a Fabric mod. It exposes the server-side Minecraft API and the Fabric API as MCP tools so an MCP client — Claude Desktop, Cursor, or any agent that speaks MCP — can read and manipulate a live world programmatically.

An agent built this over MCP — authored as a parametric voxel model, then placed in a single block_fill_batch and verified with block_render_region (the server-side render that produced no screenshot dependency — it reads block map colours straight from the world).

And Ghasticlawd — the project's Ghast × Claude mascot — voxelized, placed via block_fill_batch, and confirmed with block_render_region.

And terrain, too — this red-rock canyon, inspired by the national parks of the American West, was generated as a hydraulically eroded heightfield, render-checked, then materialized into the world through block_fill_batch and verified with block_render_region.

The mod ships separate jars for each supported Minecraft version. The build matrix in v0.2.0 is 1.21.11, 26.1.1, and 26.1.2.

Two endpoints: world + inspection

The same jar exposes two MCP servers. The main entrypoint serves the world tools on minecraft-java (default port 8765) wherever a server runs — dedicated or single-player. The client entrypoint runs inside a real, rendered client and serves an inspection-only surface on minecraft-java-client (default port 8766): view_capture returns the player's actual first-person frame as a PNG, and sense_* / client_status read client-side perception. It is the way an agent SEES the world as a player does — the real rendered pixels the headless server can't produce. Run server-only, client-only (single-player gives you both endpoints from one process), or a server+client combo. See [docs/configuration.md](docs/configuration.md#two-mcp-servers-world--inspection).

⚠️ Built on Minecraft and Fabric API internals

This mod depends on Minecraft's server-side internals via the Fabric API. The API surface evolves between Minecraft versions and a Minecraft update can change, deprecate, or remove methods this mod relies on. Pin your Minecraft installation, your Fabric API jar, and this mod's jar to known-good versions and upgrade them together. Treat the stack as experimental.

The sibling projects

This server pairs with a companion Claude Code plugin, and the whole thing is the Java Edition counterpart of an existing Bedrock stack:

| Repository | Edition | Role | | --- | --- | --- | | minecraft-java-fabric-mcp-server (this repo) | Java Edition | The MCP server, packaged as a Fabric mod. Loads inside Minecraft and exposes the Java API as MCP tools. | | minecraft-java-fabric-claude-plugin | Java Edition | The companion Claude Code plugin. Bundles the MCP connection plus setup and builder skills/agents that drive this server. | | minecraft-bedrock-mcp-server | Bedrock Edition | The Node/TypeScript MCP server for the Bedrock Dedicated Server. | | minecraft-bedrock-mcp-behavior-pack | Bedrock Edition | The companion behavior pack for the Bedrock setup. |

The plugin is optional — any MCP client (Claude Desktop, Cursor, a hand-configured claude mcp add) can talk to this server directly — but on Claude Code it's the fastest path: it wires up the connection and ships the building skills and agents. See [Connect an MCP client](#7-connect-an-mcp-client) below.

The Java and Bedrock stacks are independent — installing one has no effect on the other. They share a tone and configuration style but expose different (overlapping) tool surfaces because the Java and Bedrock Script APIs differ substantially.

How it works

MCP client (Claude Desktop, Cursor, …)
   │   MCP over Streamable HTTP, localhost-only by default
   ▼
[ Fabric mod: HTTP transport ]   ←—— Host / Origin / optional bearer validation
   │
   ▼
[ Protocol layer ] ←—— JSON-RPC 2.0 over Streamable HTTP, tool registry
   │
   ▼
[ Runtime: MinecraftMainThreadExecutor ]   ←—— marshals every world touch onto the server main thread
   │
   ▼
[ Adapter layer ]   ←—— version-stable interface; per-version implementations
   │
   ▼
the loaded Minecraft world (integrated single-player, or dedicated server)

Every tool call:

1. Arrives on an HTTP thread of the embedded JDK HttpServer.
2. Passes Host / Origin / (optional) bearer / body-size / rate-limit checks.
3. Is dispatched by the MCP layer to a tool implementation.
4. The tool submits any Minecraft API access through the main-thread executor.
5. The executor completes the work on the next server tick and returns the result.
6. The HTTP thread serializes the result to JSON and responds.

See [docs/architecture.md](docs/architecture.md) for the detailed layering rationale.

Quick start (single-player, default config)

End-to-end: a clean machine to "Claude making it rain chicken jockeys in your village." The default configuration binds to 127.0.0.1:8765, no token required, with strict Host/Origin validation that defends against DNS-rebinding and CSRF.

1. Install Java

The mod runs inside the Minecraft launcher's JVM, which the launcher itself manages — for typical single-player play you don't need to install Java separately. (You only need a system JDK if you're [building from source](#building-from-source).)

2. Install Minecraft Java Edition and the launcher

If you don't already have it, get the Minecraft Launcher from minecraft.net/download. Launch it once, sign in, and load a vanilla world to confirm the install works.

3. Install Fabric Loader

Download the Fabric Loader installer and run it. Pick the Minecraft version you want (one of 1.21.11, 26.1.1, or 26.1.2 — the versions this mod ships jars for) and click Install. The installer registers a new "fabric-loader-…" profile in the Minecraft Launcher and creates a mods/ folder under your game directory.

4. Download the mod and Fabric API

• This mod — get it from your preferred mod host and pick the jar whose suffix matches your

Minecraft version (e.g. minecraft-fabric-mcp-0.2.0+1.21.11.jar):

• Modrinth (recommended)
• CurseForge
• or the GitHub Releases page.
• Fabric API: pick the version that matches the same MC

version.

5. Install both jars

Drop both jars into your Minecraft mods/ directory:

• Windows: %APPDATA%\.minecraft\mods\
• macOS: ~/Library/Application Support/minecraft/mods/
• Linux: ~/.minecraft/mods/

6. Launch the Fabric profile

Open the Minecraft Launcher, select the fabric-loader-… profile from the dropdown, click Play, and open any world (existing or new). When the world finishes loading, the integrated server starts and the MCP listener binds to http://127.0.0.1:8765/mcp. Confirm with:

curl http://127.0.0.1:8765/healthz
# → {"status":"ok"}

7. Connect an MCP client

The mod speaks MCP over Streamable HTTP. Connect from whichever client you use.

Claude Code (CLI) — via the plugin (recommended): the companion minecraft-java-fabric-claude-plugin wires up the MCP connection and installs the setup and building skills/agents. From a Claude Code session, run:

/plugin marketplace add chapmanjw/minecraft-java-fabric-claude-plugin
/plugin install minecraft-java@minecraft-java-claude

Restart Claude Code afterward. See the plugin's README for what each skill and agent does.

Claude Code (CLI) — manual: if you'd rather connect the raw tools without the plugin, run once from a terminal —

claude mcp add --transport http minecraft-java http://localhost:8765/mcp

Claude Desktop: edit the desktop app's claude_desktop_config.json (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "minecraft-java": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8765/mcp"]
    }
  }
}

Then restart Claude Desktop. For authenticated / remote setups, see [docs/claude-desktop-integration.md](docs/claude-desktop-integration.md) and [docs/cursor-integration.md](docs/cursor-integration.md).

8. Try it

In any Claude session with the MCP server connected, ask it natural-language things like:

• "Who's online in Minecraft right now?" → player_list_online
• "Give me 64 diamonds." → player_give_item
• "Set it to noon and clear the weather." → level_set_time, level_set_weather
• "Build me a 5×5×5 box of glass at my feet." → block_fill_region
• "Find a nearby village." → entity_query for minecraft:villager
• "Make it rain chicken jockeys over the village." → 20× command_execute with

summon minecraft:chicken {Passengers:[{id:"minecraft:zombie",IsBaby:1b}]} plus level_set_weather set to thunder for atmosphere.

That last one is the canonical smoke test. If chickens with baby zombie riders rain down from the sky over your village while a thunderstorm rolls in, the whole stack is wired up correctly.

The full single-player walkthrough (with dedicated-server and LAN variants) lives in [docs/setup-singleplayer.md](docs/setup-singleplayer.md). For a dedicated server with bearer auth and remote access, see [docs/setup-dedicated-server.md](docs/setup-dedicated-server.md).

Configuration

All configuration is JSON-on-disk at /config/minecraft_fabric_mcp/config.json, with every field overridable by an environment variable (MCP_). Defaults are baked into the mod — the file only needs to exist if you're overriding something.

| Field | Default | Description | | --- | --- | --- | | host | 127.0.0.1 | Bind address. Non-loopback requires auth_required=true and allow_remote=true. | | port | 8765 | Listen port. | | auth_required | false | When true, every request must carry Authorization: Bearer . | | bearer_token | (null) | When auth_required=true and this is null, the mod generates a 32-byte hex token and writes it back into the config file. | | allow_remote | false | Required true when host is non-loopback. Belt-and-suspenders so you don't accidentally expose the listener. | | allowed_origins | [] | Browser-style Origin allow-list. Default rejects any request carrying an Origin header. | | command_timeout_ms | 15000 | Per-tool wait for main-thread work. | | rate_limit_rpm | 60 | Per-client requests per minute. | | max_body_bytes | 16777216 | Max request body. | | event_buffer_size | 1024 | Default per-subscription ring buffer size for events_* tools. | | queue_max | 256 | Max concurrent async jobs (huge bulk operations). | | log_level | info | SLF4J log level. | | tls_cert_path / tls_key_path | (null) | If both set, the listener serves HTTPS. Both must be set, or both null. | | metrics_enabled | false | Reserved for the Prometheus /metrics endpoint (v0.2.0). | | included_categories | [] | Allow-list of domain categories. If non-empty it replaces the default-ON set. One of blocks, structures, world, entities, players, items, gameplay, scripting, registries, server. | | excluded_categories | [] | Domain categories to drop. Applied after the allow-list (or the default-ON set). | | max_access | write | Access cap: read, write, or admin. Tools above the cap are dropped. The default write keeps admin/destructive tools off until you opt in. | | exclude_write_tools | false | Legacy switch, equivalent to max_access: read. When true, only read tools register. |

See [Tool categories, access levels & defaults](#tool-categories-access-levels--defaults) for the full model and worked examples.

See [docs/configuration.md](docs/configuration.md) for the full reference and recipe-style examples.

Security model summary

• The default bind is 127.0.0.1 with no token. Anything on the same machine can talk to the MCP

endpoint; nothing else can.

• The Host header is validated against the bind address — DNS rebinding attacks that resolve an

attacker-controlled domain to 127.0.0.1 still get rejected because their Host header is wrong.

• The Origin header is validated against allowed_origins (empty by default). Browsers always

send Origin on cross-origin requests; legitimate MCP clients (mcp-remote, Cursor) do not.

• Binding non-loopback requires both allow_remote: true and auth_required: true. On first run

with auth enabled, the mod generates a 32-byte hex bearer token, writes it back to the config file (with POSIX 600 permissions where supported), and logs it once.

Full threat model in [docs/security.md](docs/security.md).

Tool surface

The mod registers tools whose names follow the Minecraft Java API class convention rather than the Bedrock mc__ style. Tools group by the class or concept they operate on:

| Domain | Examples | | --- | --- | | server_* | server_get_status, server_set_motd, server_save_all_worlds | | level_* | level_set_time, level_set_weather, level_create_explosion, level_get_biome_at | | block_* | block_get_state, block_fill_region, block_fill_batch, block_scan_summary, block_render_region | | block_entity_* | block_entity_get_nbt, block_entity_set_nbt | | entity_* | entity_summon, entity_teleport, entity_apply_effect | | player_* | player_list_online, player_give_item, player_send_title | | inventory_* | inventory_get, inventory_set_slot, inventory_count_items | | itemstack_* | itemstack_describe, itemstack_drop_at | | command_* | command_execute, command_execute_as | | scoreboard_* | scoreboard_add_objective, scoreboard_set_score, scoreboard_add_team | | data_* | data_storage_get, data_attachment_set | | structure_* | structure_save_from_world, structure_load_to_world | | datapack_* | datapack_enable, datapack_disable | | loot_table_* / recipe_* / tag_* / resource_loader_* | registry-style read tools | | events_* | events_subscribe, events_poll, events_unsubscribe |

A full reference with JSON Schemas and per-version annotations lives in [docs/tools.md](docs/tools.md).

Tool categories, access levels & defaults

The 183 tools are filtered along two independent axes so you can narrow the surface by subsystem and by risk at the same time:

• Domain — which part of Minecraft the tool touches: blocks, entities, the server itself,

and so on. Ten categories, each tied to a tool-name prefix. This is the "I only care about world-building, hide the scoreboard plumbing" axis.

• Access — how dangerous the tool is: read (inspects state, mutates nothing) /build.gradle.kts` because the Fabric Loom plugin ID

differs across Minecraft versions (legacy fabric-loom for 1.21.x; net.fabricmc.fabric-loom LoomNoRemap variant for 26.1+).

Each tool declares the Minecraft and Fabric API constraints it needs via the @McpTool annotation, and the registration layer f

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chapmanjw
• Source: chapmanjw/minecraft-java-fabric-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.