MCP Fabric (Minecraft)

MCP Fabric — AI control for Minecraft

Let Claude and other MCP clients see, understand, and play Minecraft through 50+ tools.

Download on Modrinth · Installation · Tools · Security · Telemetry · Contributing

MCP Fabric is a local-first Minecraft mod and Model Context Protocol server that gives AI agents structured observation and controlled access to Minecraft. It works on both the client and dedicated servers across Minecraft 1.21.1–1.21.11 and 26.1–26.3, on Fabric and NeoForge.

• Play through natural language: move, look, navigate, mine, build, fight, and use inventory.
• See the game: inspect blocks, entities, players, status, chat, events, and screenshots.
• Operate servers: run commands, edit worlds, manage entities, and administer players.
• Bring your own AI: works with Claude Desktop, Claude Code, and other MCP-compatible hosts.
• Stay local by default: loopback-only HTTP bridge, bearer authentication, and capability gates.
• No hidden telemetry: the current Fabric release sends no usage analytics.

Quick start

1. Install Fabric Loader and Fabric API, or NeoForge.
2. Download the jar matching your Minecraft version and loader from Modrinth and place it in mods/.
3. Launch Minecraft. While it runs, the mod writes its address and token to ~/.mcpfabric/bridge.json (readable only by you), and the MCP server connects through it: no token to copy.
4. Build the MCP server with cd mcp-server && npm ci && npm run build.
5. Add it to your MCP client using the ready-to-copy examples.

[!CAUTION] MCP Fabric can grant an AI operator-level control. Keep the bridge on 127.0.0.1, keep authentication enabled, and disable capability groups you do not need.

How it works

mcpfabric has two parts: a Fabric / NeoForge mod that embeds a local HTTP bridge in Minecraft, and a small TypeScript MCP server that exposes the bridge as discoverable tools.

Claude / any MCP client
        │  MCP (stdio or streamable HTTP)
   mcp-server  (Node / TypeScript)
        │  HTTP  POST /rpc (JSON-RPC) + GET /events (SSE),  bearer token, 127.0.0.1 only
   mod "mcpfabric" on Fabric or NeoForge  (HTTP server embedded in Minecraft)
        │  all game access goes through the main-thread executor (server.execute / Minecraft.execute)
   ┌── common (env *) ─────────────┐   ┌── client (env client) ─────────────────┐
   │ info  world  entities         │   │ player  control  interact               │
   │ players  command  chat events │   │ inventory  vision  navigation  chat     │
   └───────────────────────────────┘   └─────────────────────────────────────────┘

Reads use Minecraft's native API (structured data); writes (setblock / summon / give / tp / effects / weather / time) go through the command dispatcher with output capture. Player control uses KeyMapping (integrating with the vanilla input pipeline), screenshots use the vanilla Screenshot / NativeImage, and navigation is a custom A\*.

Supported Minecraft versions

A single source tree targets many Minecraft versions using Stonecutter. Each version below ships its own jar:

14 Fabric jars are produced, each named mcpfabric-<modVersion>+<mcVersion>.jar (e.g. mcpfabric-0.3.0+1.21.8.jar). The 26.1.2 jar declares compatibility with the whole 26.1 line. They require Fabric Loader ≥ 0.19.5 and the matching Fabric API build.

13 NeoForge jars cover the same versions except 1.21.2 (NeoForge only shipped two abandoned betas for it), each named mcpfabric-neoforge-<modVersion>+<mcVersion>.jar:

NeoForge for 1.21.6, 1.21.7, 1.21.9 and 26.3 only exists as beta builds.

The MCP server needs Node.js ≥ 22.16 (the agent runtime uses the built-in node:sqlite).

1. Build the mod

# Build a single version (the one currently active in stonecutter.gradle)
./gradlew build           # Windows: gradlew.bat build

# Build a specific version (Fabric nodes are named after the version, NeoForge nodes <mc>-neoforge)
./gradlew ":1.21.8:build"
./gradlew ":1.21.1-neoforge:build"

# Build every supported version at once
./gradlew chiseledBuild

Per-version jars land in versions/<node>/build/libs/.

JDK note. 1.21.x builds need JDK 21; the 26.x line needs JDK 25. Loom requires the Gradle daemon to run on a JDK at least as new as the Minecraft version, so to build 26.x (or chiseledBuild) run Gradle on JDK 25 with JDK 21 also installed. See CONTRIBUTING.md.

Network note. If the first build fails with Remote host terminated the handshake while downloading dependencies from maven.fabricmc.net (this happens behind TLS-inspecting antivirus/firewalls), gradle.properties already pins TLS 1.2 and sequential downloads. Just re-run the build — the download cache persists.

Install

Drop the jar for your Minecraft version and loader into your mods/ folder (on Fabric, together with Fabric API):

• Client (AI plays as you): the mods/ folder of your Fabric / NeoForge instance.
• Server (AI as admin): the mods/ folder of your dedicated Fabric / NeoForge server.
• Both sides at once is fine.

On first launch the mod creates config/mcpfabric.config.json and logs where to find the token:

[mcpfabric] ready — bridge http://127.0.0.1:25599 (token: .../config/mcpfabric.config.json)

The token is intentionally not printed to logs. While the game runs, the mod also writes the bridge address and token to ~/.mcpfabric/bridge.json (readable only by your user, removed when the game stops), and the MCP server reads it when MCPFABRIC_TOKEN is not set. Set writeDiscoveryFile to false to turn that off and copy token into MCPFABRIC_TOKEN instead.

Mod config (config/mcpfabric.config.json)

{
  "host": "127.0.0.1",
  "port": 25599,
  "token": "generated automatically",
  "requireAuth": true,
  "readToken": "generated automatically",
  "callTimeoutMs": 8000,
  "worldIdKey": "generated automatically",
  "writeDiscoveryFile": true,
  "auditLog": true,
  "enableWorldWrite": true,
  "enableCommands": true,
  "enablePlayerControl": true,
  "enableVision": true,
  "enableUiControl": false,
  "enableSupervisedControl": false,
  "supervisedWorlds": [],
  "supervisedCommands": ["time", "weather"],
  "requireApproval": []
}

The enable* flags let you switch off dangerous capability groups. enableUiControl is the one that starts off: it lets the model click buttons and type into text fields of game screens (get_ui, click_widget, set_text_field), which reaches settings and actions the other tools never expose. Vanilla screens are limited to the pause, title, death, options, advancements, statistics, confirmation and container screens, but screens added by other mods are not restricted, so turn it on only when you need it, for example to test a mod's UI. It also needs enablePlayerControl. requireAuth (default true) gates every request behind the bearer token — only set it to false if you understand that it removes the sole authentication on an operator-level bridge. Keep host on 127.0.0.1 unless you fully understand the consequences — the bridge grants operator-level power. worldIdKey turns a server address into the opaque world id that session.info reports; like the token, it is never sent over the bridge.

enableSupervisedControl (off by default) turns on the supervised mode: one narrow action per call under short-lived authority, with every outcome read back or reconciled. It is its own lock, so you can turn the other enable* flags off and leave the model only these actions. supervisedWorlds lists the save folders it may open, supervisedCommands the command roots it may run. See docs/SUPERVISED.md.

2. MCP server

The server is on npm as mcpfabric-mcp-server: npx -y mcpfabric-mcp-server runs it without a checkout. To build it from source:

cd mcp-server
npm install
npm run build      # compiles to dist/

Usually your MCP client launches it for you (see below). Manually:

node dist/index.js        # finds the running game through ~/.mcpfabric/bridge.json

Environment variables

Tool sets

Every tool takes up model context, and a model chooses better from 20 tools than from 90. Set MCPFABRIC_TOOLSETS to a comma-separated list of profiles and groups to serve only those:

The other groups are ui, supervised and script (run_script and the skills), e.g. MCPFABRIC_TOOLSETS=play,ui or MCPFABRIC_TOOLSETS=supervised. get_status and list_capabilities (info) are always served. Tool sets only hide tools: the mod's enable* flags still decide what the game allows. Add readonly to serve only the tools that just read, e.g. MCPFABRIC_TOOLSETS=readonly or MCPFABRIC_TOOLSETS=play,readonly; pair it with the mod's read-only token (below).

3. Connect to Claude

Claude Desktop

One click: download mcpfabric-<version>.mcpb from the GitHub releases and open it (or drag it into Claude Desktop, or Settings → Extensions → Install Extension). It needs Node.js ≥ 22.16 and finds the running game on its own. To build it yourself: cd mcp-server && npm run bundle.

Or by hand, claude_desktop_config.json (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "mcpfabric": {
      "command": "npx",
      "args": ["-y", "mcpfabric-mcp-server"]
    }
  }
}

Claude Code

Use the .mcp.json in the project root (see examples/mcp.json) or:

claude mcp add mcpfabric -- npx -y mcpfabric-mcp-server

With the game running, the server finds it on its own. Set MCPFABRIC_URL and MCPFABRIC_TOKEN only for a game with writeDiscoveryFile: false or on another port than the one in bridge.json.

Talk to the AI from the game (Claude Code channel)

Claude Code channels (research preview) let the MCP server push messages into a running Claude Code session. With MCPFABRIC_CHANNEL=1 and the stdio transport, mcpfabric declares the claude/channel capability, keeps one event stream to the bridge open (reconnecting with a backoff) and pushes:

• your own chat messages that start with the prefix (@ai build a hut here) as kind="request"; messages from other players never count as requests;
• with MCPFABRIC_CHANNEL_WHISPERS=1, whispers other players send you, as kind="whisper" with untrusted="true" and source="player:<name>": data, never instructions;
• alerts: your player died (death), health fell below MCPFABRIC_CHANNEL_HEALTH (low_health, at most one per minute), the client was kicked or lost the connection (disconnected), and an agent job finished or failed (job).

At most MCPFABRIC_CHANNEL_RATE messages per minute are pushed; the next one after a burst says how many were dropped. The AI answers in the game with send_chat (a tool that shows a reply only to you is coming separately). The requests, whispers and alerts come from the client, so the mod has to run on the client; chat that a server plugin turns into system messages is not seen as yours.

Register the server (for example in .mcp.json) with "MCPFABRIC_CHANNEL": "1" in its env, then start Claude Code with the development flag, since custom channels are not on the research preview allowlist:

claude --dangerously-load-development-channels server:mcpfabric

Tools (50+)

info — get_status, list_capabilities world (read) — get_block, get_blocks_region, find_blocks, get_time_and_weather, list_dimensions, raycast world (write) — set_block, fill_blocks, set_time, set_weather entities — query_entities, get_entity, summon_entity, remove_entity players (admin) — list_players, get_player, teleport_player, set_gamemode, give_item, apply_effect, message_player, kick_player command — run_command (any operator-level command, with output capture) chat — send_chat, show_message (client: only the local player sees it), get_recent_chat player (local, client) — get_self, get_inventory, get_equipment, get_status_effects control (client) — set_movement, stop_movement, look, look_at, jump, start_using_item, stop_using_item interact (client) — break_block, place_block, use_item, attack_entity, use_entity, drop_held_item inventory (client) — select_hotbar_slot, drop_slot, swap_slots vision (client) — screenshot (PNG for vision models; marks: true numbers the mobs and players in view and lists their uuids), describe_scene navigation (client) — navigate_to (A\*: walks, swims, climbs ladders, opens doors, digs through blocks and pillars up), navigation_status, stop_navigation session (client) — get_screen, close_screen (pause menu, chat, container; respawns on the death screen), list_worlds, join_world (rejoin after a kick, a server restart or a game restart) ui (client, off by default: enableUiControl) — get_ui (widgets of the open screen), click_widget, set_text_field supervised (off by default: enableSupervisedControl) (docs/SUPERVISED.md) — supervised_status, supervised_stop, supervised_input (one key for up to 10 ticks), supervised_read_block, supervised_set_block (with a precondition), supervised_command (allowlisted roots), supervised_enter_world / supervised_leave_world (approved saves), supervised_reconcile events — poll_events (recent damage, deaths, chat, spawns, player join/leave; on the client also self_health, self_death and left_world)

agent runtime (docs/AGENT.md) — persistent per-world memory, goals, map and background jobs: agent_brief, observe, map_view, surroundings (mobs, items and places relative to your view), remember, recall, memory_update, memory_verify, goal_add, goal_update, goal_list, plan_craft, get_recipes, explore_next, jobs travel_to / explore / collect_blocks / craft_item with job_status / job_cancel, and open_container / container_transfer / close_container; open_dashboard shows a live panel (position, vitals, job, map, goals, inventory and a STOP button) in hosts that render MCP Apps, such as Claude

scripts (docs/AGENT.md) — code mode: one JavaScript program in a sandbox replaces dozens of tool calls: run_script; programs that worked are kept per world as skills: save_skill, list_skills, run_skill, delete_skill (the skill tools need the agent runtime)

Server tools require a running server (integrated on the client or dedicated). Client tools (control / interact / vision / navigation / player / inventory) only work on the client. Call get_status first — it reports which side you are on and which groups are available.

Benchmark

mcpfabric-bench scores agents on small tasks in a test world (collect logs, craft a stone pickaxe, find a chest, smelt iron, climb a ledge): see docs/BENCH.md.

Example prompts

• "Look around and describe what's nearby" → get_self + describe_scene (+ screenshot for a vision model).
• "Walk to these coordinates and mine diamonds" → find_blocks → navigate_to → break_block.
• "Get a stone pickaxe" → plan_craft → collect_blocks (logs, stone) → craft_item; progress is kept in the goal tree and memory, so a later session resumes with agent_brief.
• "What's happening on the server" → list_players + poll_events.
• "Build a wall" → fill_blocks or a series of set_block / run_command.

Taking control back

On the client, press K (rebind it under Controls → Miscellaneous) or run /mcpfabric stop to pause the AI: the keys it holds are released, navigation, mining and supervised grants stop, and every action over the bridge is refused until you press K again or run /mcpfabric resume. Reads keep working, and the AI can still answer you with show_message. /mcpfabric status shows the state; get_status reports it to the model as aiPaused, and the events ai_paused and ai_resumed are emitted. When the AI starts acting after a quiet spell, the action bar says so.

Approving risky calls

List capability groups in requireApproval ("command", "world_write", "players_admin") and each call of those groups waits until you answer it in the game: the request shows in chat and on the action bar, Y approves and N denies the oldest one (rebindable), or /mcpfabric approve|deny [id]. No answer within 60 seconds is a denial, and pausing the AI denies everything that waits. get_status reports the list as requireApproval. Only a client can answer: on a dedicated server those groups are then refused.

Security

• The bridge listens on 127.0.0.1 only and requires a bearer token.
• Operator-level capabilities (run_command, world writes, player control) are on by default — this gives the AI full control. Turn off groups with the enable* flags if you need to, and use enableSupervisedControl if the model should only take single, approved actions.
• Text that other players or the world wrote (chat, whispers, signs, books, item and entity names, screen titles, command output) is data, not instructions. Tools whose results can carry it return { "untrusted": true, "notice": ..., "data": ... }, and chat entries carry a source (player:<name> or server); the server instructions tell the model the same.
• readToken is a second bearer token that may only read the game (blocks, entities, players, chat history, events, perception, screenshots; each still behind its own lock): give it to a model or tool that should watch but not act, together with MCPFABRIC_TOOLSETS=readonly, which serves only the read-only tools. Any other method is refused with forbidden.
• Every call with a lasting effect (commands, block and entity edits, player admin, chat, interactions, screens, supervised actions) is recorded in logs/mcpfabric-audit.jsonl with its time, outcome and a short form of its params; movement, looking and reads are not. It rolls over at 5 MiB. Set auditLog to false to turn it off.
• Do not expose host externally without understanding the risk and putting an authenticated reverse proxy in front of it. See SECURITY.md.

Project structure

mcpfabric/
├─ settings.gradle, stonecutter.gradle                 # Stonecutter nodes (version × loader)
├─ build.gradle, build.neoforge.gradle                 # Fabric Loom / NeoForge ModDevGradle builds
├─ gradle/common.gradle, gradle/modrinth.gradle        # shared by both loaders
├─ gradle.properties                                   # shared build config
├─ versions/<node>/gradle.properties                   # per-node Minecraft + loader versions
├─ src/main/java/dev/mcpfabric/                         # common (env *): bridge + server handlers
│  ├─ McpFabric.java, ServerHolder.java
│  ├─ platform/    (Platform: the loader services the shared code needs)
│  ├─ fabric/, neoforge/   (loader entrypoints; only the node's own loader is compiled)
│  ├─ bridge/      (HttpBridgeServer, RpcRouter, MainThread, SseHub, Json, ...)
│  ├─ config/      (McpConfig)
│  ├─ events/      (EventBus, GameEvent)
│  └─ handlers/    (Info/World/Entity/PlayerAdmin/Command/Chat + support/CommandRunner, Levels)
├─ src/client/java/dev/mcpfabric/client/                # client (env client): bot + client handlers
│  ├─ McpFabricClient.java, ClientMc.java, BotController.java, ClientEvents.java
│  ├─ fabric/, neoforge/   (loader client entrypoints)
│  ├─ nav/AStarPathfinder.java
│  └─ handlers/    (LocalPlayer/Control/Interact/Inventory/Vision/Nav/ClientChat)
└─ mcp-server/                                          # MCP server (TypeScript)
   ├─ src/index.ts, bridge.ts, tools.ts, config.ts
   └─ package.json, tsconfig.json

See CONTRIBUTING.md for the multi-version workflow and how to add a Minecraft version.

License

MIT.